Skip to content

docs: Add crewai-soul as community memory backend#4755

Open
menonpg wants to merge 2 commits intocrewAIInc:mainfrom
menonpg:add-crewai-soul-community-backend
Open

docs: Add crewai-soul as community memory backend#4755
menonpg wants to merge 2 commits intocrewAIInc:mainfrom
menonpg:add-crewai-soul-community-backend

Conversation

@menonpg
Copy link

@menonpg menonpg commented Mar 6, 2026

Summary

Adds crewai-soul to the Memory documentation as a community backend option for users who prefer markdown-based, git-versionable memory storage.

What is crewai-soul?

A drop-in memory backend that stores agent memories in human-readable markdown files (SOUL.md + MEMORY.md).

Why users might prefer it:

  • Human-readable — See exactly what agents remember
  • Git-versionable — Track memory evolution with commits
  • Editable — Fix wrong memories by editing files
  • No database — Just markdown files

Built on:

Links

Changes

  • Added "Community Memory Backends" section to docs/en/concepts/memory.mdx
  • Documented installation, usage, and when to choose crewai-soul over default Memory

Note

Low Risk
Low risk documentation-only change with no runtime or API impact.

Overview
Adds a new Community Memory Backends section to docs/en/concepts/memory.mdx introducing crewai-soul as an alternative, community-maintained memory backend.

Documents when to use it, how to install it, a minimal standalone usage example, and links to its GitHub/PyPI plus a short feature list.

Written by Cursor Bugbot for commit a1df2d7. This will update automatically on new commits. Configure here.

Added crewai-soul to the Memory documentation as a community alternative
for users who prefer:
- Human-readable markdown storage (SOUL.md + MEMORY.md)
- Git-versionable memory
- Manual memory editing capabilities
- File-based storage over databases

Links to PyPI, GitHub, and comparison article included.
Copilot AI review requested due to automatic review settings March 6, 2026 23:48
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds a "Community Memory Backends" section to docs/en/concepts/memory.mdx, documenting crewai-soul — a third-party package that stores agent memories in markdown files (SOUL.md + MEMORY.md) for human-readable, git-versionable memory storage.

Changes:

  • Adds a new ## Community Memory Backends section to the core memory concept page
  • Documents crewai-soul installation, usage, features, and links
  • Provides a usage example showing SoulMemory() as a direct Crew memory= argument

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

```markdown
# Memory Log

## 2026-03-06 18:30:15 UTC
Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example output in the markdown code block contains the hardcoded date 2026-03-06 18:30:15 UTC. This is a specific real-world date that will quickly become outdated and confusing to readers. Documentation examples should use a generic or placeholder date (e.g., YYYY-MM-DD HH:MM:SS UTC or a clearly illustrative date like 2024-01-15) rather than a specific timestamp tied to when this PR was authored.

Suggested change
## 2026-03-06 18:30:15 UTC
## YYYY-MM-DD HH:MM:SS UTC

Copilot uses AI. Check for mistakes.
Comment on lines +787 to +794
from crewai import Crew
from crewai_soul import SoulMemory

# Drop-in replacement for Memory
crew = Crew(
agents=[researcher, writer],
tasks=[...],
memory=SoulMemory(),
Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code comment on line 790 describes SoulMemory() as a "Drop-in replacement for Memory", but the existing documentation (line 761) clearly states that custom storage backends should be passed as Memory(storage=your_backend) via the StorageBackend protocol. If SoulMemory is a completely separate class (not a Memory subclass or StorageBackend implementation), passing it directly as memory=SoulMemory() to Crew may not actually work with CrewAI's Crew constructor, which likely expects a Memory instance or True. This claim of being a "drop-in replacement" should be verified against CrewAI's actual type expectations, and the usage example should be updated to reflect the correct integration pattern (e.g., Memory(storage=SoulMemory()) if it implements StorageBackend).

Suggested change
from crewai import Crew
from crewai_soul import SoulMemory
# Drop-in replacement for Memory
crew = Crew(
agents=[researcher, writer],
tasks=[...],
memory=SoulMemory(),
from crewai import Crew, Memory
from crewai_soul import SoulMemory
# Use SoulMemory as a custom storage backend for Memory
crew = Crew(
agents=[researcher, writer],
tasks=[...],
memory=Memory(storage=SoulMemory()),

Copilot uses AI. Check for mistakes.
**Links:**
- [GitHub](https://github.com/menonpg/crewai-soul)
- [PyPI](https://pypi.org/project/crewai-soul/)
- [Comparison: crewai-soul vs CrewAI Memory](https://menonlab-blog-production.up.railway.app/blog/crewai-soul-vs-crewai-memory)
Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comparison article link points to a third-party blog hosted on menonlab-blog-production.up.railway.app, a Railway-hosted deployment. Railway-hosted apps can go offline or become unavailable at any time. Official CrewAI documentation should not include links to ephemeral third-party deployments, as they create a poor experience when the link becomes broken. Consider linking to a more stable hosting location, or removing the comparison link from the official docs.

Suggested change
- [Comparison: crewai-soul vs CrewAI Memory](https://menonlab-blog-production.up.railway.app/blog/crewai-soul-vs-crewai-memory)

Copilot uses AI. Check for mistakes.
Comment on lines +807 to +817
**Features:**
- RAG + RLM hybrid retrieval via [soul-agent](https://github.com/menonpg/soul.py)
- Human-readable markdown files
- Git-versionable memory
- Managed cloud option ([SoulMate](https://menonpg.github.io/soulmate)) for production
- Database schema intelligence via [soul-schema](https://github.com/menonpg/soul-schema)

**Links:**
- [GitHub](https://github.com/menonpg/crewai-soul)
- [PyPI](https://pypi.org/project/crewai-soul/)
- [Comparison: crewai-soul vs CrewAI Memory](https://menonlab-blog-production.up.railway.app/blog/crewai-soul-vs-crewai-memory)
Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR embeds a community/third-party package (crewai-soul) directly into the core concept page memory.mdx. Looking at how other third-party integrations are documented in this repository, each integration has its own dedicated page (e.g., docs/en/observability/galileo.mdx, docs/en/observability/langfuse.mdx, etc.), rather than being embedded inside a core concept file. The pattern of adding a "Community Memory Backends" section within memory.mdx deviates from the established convention. Consider either giving crewai-soul its own page (e.g., docs/en/integrations/crewai-soul.mdx) and linking to it from memory.mdx, or clearly establishing and following a consistent pattern for community backend documentation.

Suggested change
**Features:**
- RAG + RLM hybrid retrieval via [soul-agent](https://github.com/menonpg/soul.py)
- Human-readable markdown files
- Git-versionable memory
- Managed cloud option ([SoulMate](https://menonpg.github.io/soulmate)) for production
- Database schema intelligence via [soul-schema](https://github.com/menonpg/soul-schema)
**Links:**
- [GitHub](https://github.com/menonpg/crewai-soul)
- [PyPI](https://pypi.org/project/crewai-soul/)
- [Comparison: crewai-soul vs CrewAI Memory](https://menonlab-blog-production.up.railway.app/blog/crewai-soul-vs-crewai-memory)
## Community memory backends
CrewAI supports community-maintained memory backends that build on top of the core
`Memory` interface. For example, the `crewai-soul` package provides a PostgreSQL- and
markdown-based backend. For setup and usage details, see the dedicated integration
guide: [crewai-soul integration](/integrations/crewai-soul).

Copilot uses AI. Check for mistakes.
- Changed example date to placeholder YYYY-MM-DD HH:MM:SS UTC
- Removed 'drop-in replacement' claim, show standalone usage instead
- Removed Railway blog URL (ephemeral hosting concern)
- Simplified to show crewai-soul's own API rather than Crew integration
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants