# Memco Docs > Memco provides a governed continual learning memory layer for AI agents, connecting via MCP. --- # Memco Documentation URL: https://docs.memco.ai/ Memco is a memory platform for AI agents. It connects to coding agents, knowledge workers, and other AI tools via [MCP](https://modelcontextprotocol.io/), and to agents and products you build yourself via the [Python and Node.js SDKs](/sdk), and makes their knowledge persistent and portable. Memco offers two complementary products: **[Shared Memory](/mcp/overview)** is the core Memco product. It makes knowledge cumulative across your team: every agent contributes to a common pool, and every agent benefits from what others have learned. A pattern identified by one agent becomes available to all others without any explicit transfer step. A new agent joining a codebase or workflow immediately has access to the accumulated knowledge of every session that preceded it. Shared Memory includes trust scoring, multi-agent learning, and governed curation. **[Personal Memory](/personal-memory/overview)** stores your individual preferences, working style, and context in a single place that every AI agent you use can access. It is private to you and portable across agents: switch between Claude, ChatGPT, Cursor, or any other MCP-compatible client and your agents already know how you work. ## Key concepts **Knowledge domains.** Memco organizes knowledge by domain. Each domain defines the semantics for how knowledge is created, searched, and tagged within a specific area of work. Memco ships with two built-in domains: `coding` for software development workflows and `knowledge` for broader knowledge work. [Learn more about domains.](/concepts/knowledge-domains) **Trust.** Every piece of knowledge in Memco carries a trust score, computed from a Bayesian evidence model called TrustDist. Trust reflects the weight of accumulated evidence — retrievals, relevance signals, enrichments — and decays naturally when a memory stops receiving signal. [Learn more about trust.](/concepts/trust) **Memory networks.** Organizations can structure shared memory along their own boundaries — teams, departments, projects — with controlled knowledge sharing across levels. Read access flows upward through the hierarchy; write access is always local to the most specific context. ## Getting started ### Shared Memory The fastest path to using Shared Memory is connecting your agent via MCP: 1. [Quickstart](/quickstart) — connect Memco to your agent in under 5 minutes 2. [MCP tools reference](/mcp/tools-reference) — the complete tool surface your agent gets 3. [How Memco works](/concepts/how-memco-works) — the memory lifecycle from creation to retrieval ### Personal Memory 1. [Personal Memory overview](/personal-memory/overview) — what it is, how to set it up, and how it relates to Shared Memory 2. [Personal Memory tools reference](/personal-memory/tools-reference) — the complete tool surface ### Building with the SDK If you are building the agent yourself, or building memory into a product for your own customers, the SDKs give your code the same operations MCP gives an agent. 1. [SDK overview](/sdk) — install `memcoai` (Python), `@memco/memcoai` (Node.js), or `github.com/memcoai/memcoai/go/memcoai` (Go), and when to use the SDK instead of MCP 2. [Building an agent with the SDK](/sdk/building-an-agent) — the learning loop and the toolset export for LangChain, Anthropic, and OpenAI 3. [Embedding memory in your product](/sdk/embedding-memory) — memory networks and the users of your product --- # Quickstart URL: https://docs.memco.ai/quickstart/ This guide connects Memco to your AI agent. By the end, your agent will be able to search shared knowledge, contribute new memories, and provide feedback. ## Prerequisites You need a Memco account. If you do not have one, [sign up at memco.ai](https://memco.ai) to create one. ## Connect your coding agent The fastest way to connect Memco to a coding agent is through the Memco plugin marketplace. ### Claude Code Run inside Claude Code: ``` /plugin marketplace add memcoai/marketplace /plugin install shared-memory@memco ``` ### Codex ``` codex plugin marketplace add memcoai/marketplace codex plugin add shared-memory@memco ``` Or run `codex` and open `/plugins` to browse and install interactively. ### Cursor 1. Open **Dashboard → Settings → Plugins**. 2. Under **Team Marketplaces**, choose **Add Marketplace → Import from Repo** and point it at `memcoai/marketplace`. 3. Reload Cursor (**Developer: Reload Window**). 4. Open the marketplace panel and install **memco-shared-memory**. The plugin handles everything: it registers the Memco MCP server with your agent and provides the instructions your agent needs to use it. There is no need to separately configure an MCP connection or add agent instructions. The same marketplace also carries `personal-memory@memco`, the plugin for [Personal Memory](/personal-memory/overview), which is a separate product with its own MCP server. ## Connect your AI assistant If you use Memco with a general-purpose AI assistant — Claude Desktop, Claude on the web, Cowork, ChatGPT, Grok, or similar — you need to do two things: connect the Memco Shared Memory server, and instruct your agent to use it. ### Step 1: Connect Memco Shared Memory **Claude and Claude Desktop** — Memco Shared Memory is in Anthropic's connector directory. Go to **Settings → Connectors**, find **Memco Shared Memory**, and connect. You will be asked to sign in with your Memco account. **ChatGPT** — install the **Memco Shared Memory** plugin from the plugin directory. **Other assistants** — add the MCP server through the assistant's MCP or integrations settings. The endpoint is: ``` https://spark.memco.ai/mcp ``` Authentication is handled via OAuth. You will be redirected to sign in the first time you connect. ### Step 2: Instruct your agent to use it Adding the MCP server makes the tools available, but your agent also needs to know it should use them. Add the following to your project instructions, custom instructions, or system prompt: ``` You have access to a shared memory server through the Memco Shared Memory MCP server. Use that to look for findings others have shared, and to save useful knowledge with other members of the team. ``` This tells the agent to search Memco for relevant knowledge before answering, and to save useful findings back for the rest of the team. Where to put this depends on your assistant: - **Claude** — add to your project instructions, or to **Settings → Profile → User preferences** for it to apply across all conversations - **ChatGPT** — add to **Personalization → Custom Instructions** - **Grok** — add to your system prompt or custom instructions In the first few sessions, Memco is mostly listening. After a few days of use, you will start to notice your agent surfacing knowledge from previous sessions and from your teammates' work. ## Connect via MCP directly If your agent does not support the plugin marketplace or the connector directory, you can configure the MCP connection manually. This requires two steps: adding the Memco MCP server to your agent's configuration, and instructing your agent to use it (for example, in your project's `AGENTS.md` or equivalent instructions file). Your Memco MCP endpoint is: ``` https://spark.memco.ai/mcp ``` Authentication is handled via OAuth. When your MCP client connects for the first time, it will redirect you to sign in and authorize the connection. Alternatively, you can authenticate using an API key generated from the [Memco dashboard](https://spark.memco.ai/). **Claude Desktop** — the directory connector above is the supported route. If you need a manual configuration, add the following to your `claude_desktop_config.json`: ```json { "mcpServers": { "memco-shared-memory": { "url": "https://spark.memco.ai/mcp" } } } ``` **Cursor** — add to your MCP settings in `.cursor/mcp.json`: ```json { "mcpServers": { "memco-shared-memory": { "url": "https://spark.memco.ai/mcp" } } } ``` **Claude Code** — add from the command line: ```bash claude mcp add memco-shared-memory --transport streamable-http https://spark.memco.ai/mcp ``` ## Verify the connection Once connected, your agent should have access to Memco's tools. Ask your agent to list the available domains: > "What Memco domains do I have access to?" A typical response includes `coding` for software development and `knowledge` for broader knowledge work. ## Search and contribute Your agent can now search for existing knowledge: > "Search Memco for best practices on error handling in this codebase" And contribute new knowledge when it learns something useful: > "Save this as a memory in Memco — the payments service requires idempotency keys on all POST requests" The agent handles the tool calls automatically. No code changes or API integration are needed beyond the initial configuration. ## Next steps - [Learning on the Job](/examples/learning-on-the-job) — a complete runnable example: an agent learning a business's policies from reviewer corrections, with a measured learning curve - [MCP overview](/mcp/overview) — how the MCP connection works, including multi-domain support - [MCP tools reference](/mcp/tools-reference) — the complete tool surface - [How Memco works](/concepts/how-memco-works) — the memory lifecycle in detail - [Knowledge domains](/concepts/knowledge-domains) — how domains shape what your agents learn --- # How Memco Works URL: https://docs.memco.ai/concepts/how-memco-works/ Memco is built around a continuous loop: agents contribute knowledge, the system curates it, agents retrieve and use it, and their feedback drives further improvement. This page describes each stage of that lifecycle. ## The memory lifecycle ### 1. Contribution Agents contribute knowledge to Memco through two MCP tools: - `create_memory` submits a new piece of knowledge to the shared memory store. The agent provides the content and any relevant tags; Memco handles ingestion, trust initialization, and indexing. - `enrich_memory` adds information to an existing memory — for example, attaching the outcome of a task to the memory that informed it. Contributions land in the agent's writable memory network (the most specific scope available to them) and are immediately available to other agents in that network and any child networks below it. ### 2. Autonomous curation Once knowledge enters the store, Memco's curation layer — called Memory Ops — takes over. Memory Ops runs continuously without human intervention, applying a set of operators to keep the knowledge base coherent and high quality. **Knowledge synthesis** discovers new knowledge from patterns across related memories. When multiple memories share a common underlying pattern, synthesis operators can abstract that pattern into a new, higher-level insight. The original memories remain intact; the synthesized insight is a new entity that earns trust independently. **Deduplication** identifies and merges memories that capture the same knowledge in different words. This is inevitable in a multi-agent system where different agents, or even the same agent across sessions, may independently discover the same pattern. **Conflict resolution** detects memories that contradict each other and resolves the conflict based on evidence. When two memories make incompatible claims, the system uses trust scores and evidence mass to determine which reflects the stronger signal. **Safety filtering** screens contributed knowledge against quality and safety criteria before it enters the active knowledge base. **Pruning** removes knowledge that has accumulated strong negative evidence or has become stale through lack of use. This keeps the knowledge base focused on what is currently valuable. ### 3. Retrieval When an agent calls `search`, Memco queries the knowledge store using hybrid retrieval: a combination of vector search (semantic similarity), full-text search (keyword matching), and trust-weighted ranking. Results are drawn from all memory networks the agent has read access to — their own writable network plus every ancestor in the hierarchy above it. Memco uses an exploration/exploitation mechanism to balance retrieval. High-trust memories are reliably surfaced, but memories with less evidence are selectively included to give them the opportunity to accumulate further signal. This prevents the knowledge base from converging prematurely on a fixed set of memories while newer or less-tested knowledge languishes unseen. ### 4. Feedback After using retrieved knowledge, agents call `share_feedback` to rate the relevance and correctness of the results they received. These ratings feed directly into the trust model as evidence. A memory that consistently receives positive feedback accumulates trust and is surfaced more reliably. A memory that receives negative feedback loses trust and is eventually pruned. Implicit signals also contribute: when agents enrich existing memories, or create new memories that build on what they found, these actions reinforce the value of the source material. ## The learning loop These four stages form a closed loop. Contributions enter the store. Curation keeps the store coherent. Retrieval surfaces relevant knowledge. Feedback refines trust scores. Updated trust scores feed into subsequent retrievals and curation decisions. The result is a knowledge base that improves continuously with use, without requiring any explicit curation effort from the team. Every agent session — every search, every feedback signal, every contribution — makes the shared memory more useful for the next session. ## System architecture Memco is built around four subsystems: **Client I/O** handles all inbound and outbound communication. Agents connect via MCP; the CLI provides an equivalent interface for scripted and non-interactive use cases. Analytics and admin APIs support operational observability and configuration. **Trust modeling** assigns and maintains a trust score for every piece of knowledge. Scores are computed using TrustDist, a Bayesian evidence model where each signal updates the underlying probability distribution rather than a scalar value. See [Trust](/concepts/trust) for details. **Memory Ops** is the autonomous curation layer described above. **Hybrid retrieval and storage** combines vector search, full-text search, and trust-weighted ranking behind a unified query interface. All subsystems operate behind a security layer covering authentication, firewall, and SSO. --- # Knowledge Domains URL: https://docs.memco.ai/concepts/knowledge-domains/ A Memco domain defines the semantics for how knowledge is created, searched, and tagged within a specific area of work. Domains shape the behavior of Memco's MCP tools — the same underlying tools (`search`, `create_memory`, `enrich_memory`) operate across all domains, but the domain determines what tags mean, how context is interpreted, and what metadata the agent should provide. ## Why domains exist Different kinds of work produce different kinds of knowledge. A coding agent learns patterns about APIs, error handling, and architectural conventions. A knowledge worker learns about processes, policies, stakeholder preferences, and domain-specific terminology. These are different shapes of knowledge, and the system that curates, retrieves, and synthesizes them needs to understand those differences. Domains provide that understanding. Each domain configures: - **Tag semantics** — which tags carry specific meaning and how they should be used. In the coding domain, a `language` tag denotes a programming language; in the knowledge domain, it might not exist at all. - **Tool descriptions** — the MCP tool descriptions presented to the agent are tailored to the domain, guiding the agent toward appropriate use of search, creation, and enrichment for that kind of work. - **Curation behavior** — Memory Ops operators (synthesis, deduplication, conflict resolution) can apply domain-specific heuristics when processing knowledge. ## Built-in domains Memco ships with two built-in domains. ### Coding The `coding` domain is optimized for software development workflows. It is designed for use with coding agents such as Claude Code, Cursor, Windsurf, GitHub Copilot, and similar tools. Knowledge in the coding domain typically includes: API patterns and conventions, error handling strategies, architectural decisions, dependency-specific behaviors, testing patterns, deployment procedures, and codebase-specific knowledge that agents discover during development sessions. The coding domain defines tags such as `language` (programming language), `framework`, and `repository` to help organize and retrieve knowledge relevant to the agent's current development context. ### Knowledge work The `knowledge` domain is designed for broader knowledge work beyond software development. It supports agents operating in areas such as research, analysis, consulting, operations, and any work that involves accumulating and applying structured knowledge over time. Knowledge in this domain typically includes: process knowledge, policy and compliance information, stakeholder and organizational context, domain-specific terminology and definitions, analytical frameworks, and procedural knowledge. ## Multi-domain access A single MCP connection provides access to all domains available in your workspace. Your agent discovers available domains — including their descriptions, tag vocabularies, and usage guidance — by calling `list_domains`. When calling `search`, `create_memory`, or other tools, the agent passes a session ID that identifies the working context, including the domain. The agent starts a session in a domain with `start_session`, then uses that session ID throughout the task. See the [MCP overview](/mcp/overview) for details on how multi-domain support works at the protocol level. ## Domain isolation Knowledge in different domains is fully isolated. A search in the coding domain does not return results from the knowledge domain, and vice versa. This isolation is deliberate: mixing knowledge across domains with different semantics would reduce retrieval precision and make curation less effective. Memory networks (the organizational hierarchy described in [How Memco works](/concepts/how-memco-works)) operate within a single domain. An organization's coding memory network hierarchy is separate from its knowledge work memory network hierarchy. To see the knowledge work domain in action, [Learning on the Job](/examples/learning-on-the-job) is a runnable example of an agent learning a business's policies through it, with a measured learning curve. --- # Trust URL: https://docs.memco.ai/concepts/trust/ Every piece of knowledge in Memco carries a trust score. Trust is a live quantity, computed from accumulated evidence, that reflects how reliably a memory has performed when surfaced to agents. It is central to how Memco decides what to retrieve, what to keep, and what to prune. ## TrustDist Memco uses an evidence-based trust model called TrustDist. Rather than assigning a static rating to each memory, TrustDist maintains a probability distribution that captures both the current trust level and how confident the system is in that assessment. This means the system distinguishes between a memory that has a trust score of 0.8 based on limited evidence (still uncertain) and one that has the same score based on extensive evidence (high confidence). A simple scalar score would treat these identically. TrustDist does not. ## How trust is earned Trust is earned through use. The primary evidence channels are: **Agent feedback.** When an agent calls `share_feedback` after using search results, the relevance and correctness ratings update the trust distribution directly. This is the primary evidence channel. **Retrieval and use patterns.** Memories that are consistently retrieved and acted on accumulate positive evidence. Memories that are retrieved but ignored or contradicted accumulate negative evidence. **Enrichment.** When an agent enriches a memory with additional context via `enrich_memory`, the act itself is a positive signal: the agent found the memory valuable enough to build on. ## How trust shapes retrieval Trust directly affects which memories appear in search results and how they are ranked. Higher-trust memories are surfaced more reliably. But Memco also ensures that newer or less-tested knowledge gets a fair chance to prove itself, rather than being permanently overshadowed by established memories. The system balances returning knowledge it is confident about with selectively surfacing knowledge that has not yet accumulated enough evidence to be judged definitively. This prevents the knowledge base from converging prematurely on a fixed set of well-known memories while potentially valuable newer knowledge goes unseen. ## Trust initialization New memories do not start with a blank slate. Memco sets an initial trust level based on available signals: **Agent-contributed memories** receive an initial trust informed by the contributing agent's own track record. An agent that has consistently produced useful knowledge gives its new contributions a stronger starting position. **Synthesized memories** — those produced by Memco's autonomous curation operators — receive an initial trust derived from the quality of the source material and the reliability of the synthesis process. After initialization, the synthesized memory earns trust independently based on its own usage. In both cases, the initial evidence is deliberately limited so that early feedback has a meaningful effect on the memory's trajectory. ## Trust and the knowledge lifecycle Trust connects directly to Memco's curation layer. Memories that accumulate sustained negative evidence, or that fail to attract any evidence over time, are eventually pruned from the knowledge base. Memories that receive positive feedback grow in trust and become more reliably available. There is no fixed decay schedule. A memory that stops being retrieved simply stops accumulating evidence. As the knowledge base grows and newer memories emerge, older memories with stagnant evidence naturally lose relative standing. If a stale memory is retrieved again and receives positive feedback, its trust recovers. The result is a knowledge base that self-regulates: useful knowledge persists and strengthens, while outdated or incorrect knowledge fades without requiring manual cleanup. --- # Privacy URL: https://docs.memco.ai/concepts/privacy/ Memco stores knowledge, not source material. Understanding the distinction is central to how Memco handles data privacy. ## What Memco stores When an agent contributes a memory, Memco stores the abstract insight — the pattern, the solution approach, the lesson learned — rather than the underlying code, documents, or data that led to it. For example, a coding agent that discovers a retry pattern for a specific API will contribute a memory describing the pattern and why it works. Memco stores that description. It does not store the source code the agent was working on, the files it read, or the repository contents. Similarly, a knowledge work agent that learns a procurement approval process will contribute the process knowledge, not the documents or emails it learned it from. This means Memco's knowledge base contains operational know-how — the kind of tribal knowledge that experienced team members carry in their heads — rather than copies of proprietary assets. ## Workspace isolation Each team's workspace is fully private. Knowledge stored by your team is visible only to members of your workspace. There is no cross-workspace visibility, and no mechanism for knowledge to leak between organizations. Within a workspace, agents can only read and write to memory networks they have been granted access to. Knowledge flows upward through the network hierarchy (a team-level agent can read organization-level knowledge), but never sideways between peer networks without explicit configuration. ## Access control Access to knowledge within a workspace is governed by role-based access control (RBAC). Workspace administrators assign permissions to team members, controlling who can read, write, and administer each memory network. Administrators can: - Grant and revoke access to specific memory networks - Assign roles that determine read, write, and admin permissions - Manage team membership and onboarding All access decisions are enforced server-side. An agent inherits the permissions of the user it is authenticated as — it can only search and contribute to memory networks that user has access to. ## Security and compliance MemCo Labs, Inc. holds a SOC 2 Type 2 certification, independently audited to verify that our systems meet the Trust Services Criteria for security, availability, and confidentiality. Our security practices include: - **Encryption in transit and at rest.** All data is encrypted using industry-standard protocols. - **Regional data residency.** Organizations can configure which region their data resides in. Once set, data never leaves the designated region. See [Regional routing](/mcp/overview#regional-routing) for details. - **Authentication and authorization.** OAuth 2.0 for interactive use, API keys for programmatic access, with RBAC governing all data access. - **Audit logging.** Administrative actions and access patterns are logged for compliance and operational visibility. - **Secure infrastructure.** Memco runs on hardened cloud infrastructure with network isolation, firewall rules, and SSO integration for enterprise customers. For questions about security practices, compliance documentation, or enterprise requirements, contact [support@memco.ai](mailto:support@memco.ai). --- # MCP Overview URL: https://docs.memco.ai/mcp/overview/ Memco Shared Memory exposes its full functionality through a single [MCP](https://modelcontextprotocol.io/) endpoint. Any MCP-compatible agent can connect to Memco and immediately begin searching, contributing, and building on shared knowledge. This page covers the Shared Memory MCP server. For Personal Memory, see the [Personal Memory documentation](/personal-memory/overview). ## Endpoint ``` https://spark.memco.ai/mcp ``` This is the Shared Memory endpoint for all Memco users, across all domains and all organisations. There is no need to configure separate endpoints per domain, organisation, or region. Personal Memory uses a separate endpoint (`https://spark.memco.ai/mcp-personal`). ### Regional routing Memco is deployed across multiple regions. The global endpoint automatically routes each request to the region where the authenticated user's organization data resides. This routing is transparent to the client — agents always connect to `spark.memco.ai/mcp` and Memco handles the rest. Data residency for a memory network can be configured through the organization's Memco dashboard. Once set, data never leaves the designated region, even though every agent connects to the same global endpoint. ## Authentication Memco uses OAuth 2.0 for authentication. When an MCP client connects for the first time, it initiates an OAuth flow that redirects the user to sign in and authorize the connection. Subsequent connections reuse the stored credentials. For programmatic access (CI/CD pipelines, scripts, automated agents), API keys are available through the Memco dashboard. If you are writing the code that drives the agent, the [Python and Node.js SDKs](/sdk) expose the same operations as this MCP server without the MCP layer in between. ## Multi-domain support A single MCP connection exposes tools that work across all domains in your workspace. **`list_domains`** returns the domains the authenticated user has access to, along with the full description of each one: what it holds, when to search it, the tag vocabulary it uses, and guidance on how to use the core tools within that domain. This is typically the first call an agent makes after connecting. The remaining tools use a session ID to identify the working context. The agent starts a session in a domain with `start_session`, then passes the session ID to subsequent calls. ## Tool surface Memco provides eight MCP tools: | Tool | Purpose | |---|---| | `list_domains` | Discover available domains and their semantics | | `start_session` | Begin a session grouping related searches in a domain | | `search` | Retrieve relevant knowledge | | `get_memory` | Fetch the full content of a previously returned memory | | `create_memory` | Contribute new knowledge | | `enrich_memory` | Add context to existing knowledge | | `share_feedback` | Rate the relevance and correctness of search results | | `revert_memory` | Undo a recently created or enriched memory | See the [Tools reference](/mcp/tools-reference) for the complete specification of each tool, including parameters, return types, and usage examples. ## Sessions A session groups related searches and contributions made while working on a single task. Starting a session with `start_session` returns a session ID that the agent passes to `search`, `create_memory`, `enrich_memory`, and `share_feedback`. The session ID identifies the working context for each call, including the domain and the set of memories referenced during the task. ## How agents use the tools A typical agent session follows this pattern: 1. **Discovery.** On first connection, the agent calls `list_domains` to learn which domains are available and how to use them. 2. **Session.** The agent calls `start_session` to begin a session in the relevant domain. 3. **Search.** When the agent encounters a task, it calls `search` with a query, tags, and the session ID. Memco returns a ranked list of memories. 4. **Feedback.** The agent calls `share_feedback` to rate the relevance and correctness of the search results it received. 5. **Contribution.** When the agent discovers something new — a pattern, a solution, a piece of context — it calls `create_memory` to share it with the team. If it has additional context for an existing memory, it calls `enrich_memory`. This cycle repeats throughout the session. The agent does not need to manage any state beyond the session ID; Memco handles persistence, trust scoring, and curation. ## Transport Memco supports the Streamable HTTP transport defined in the MCP specification. This is the recommended transport for all production use. ## Rate limits Memco applies rate limits per workspace to ensure fair resource allocation. Current limits are published in the Memco dashboard. If your workspace requires higher throughput, contact support. --- # Seed Your Workspace URL: https://docs.memco.ai/mcp/seed-your-workspace/ A new Memco workspace is empty, and shared memory only pays off once there is something to find. The seeding process extracts durable knowledge from what is already on your machine and writes it into your workspace, where every agent on your team can access it. Three kinds of source hold what you are after: | Source | What it is | Effort | |---|---|---| | **Sessions** | Months of agent transcripts (Claude Code, Codex, Cursor, ChatGPT exports) | Large and noisy. The seeding process writes a filter to extract the signal, which is typically 1-5% of the raw data. | | **Remembered notes** | What an agent wrote down for itself across past sessions (`~/.claude/projects/*/memory/`) | Already distilled. Read directly. | | **Instruction files** | Standing rules: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, editor rules | Already distilled. Read directly. | You run it once, when the workspace is new. Sessions can take a while; the file sources take minutes. ## What it does Seeding walks through several stages: 1. **Find.** The agent locates sessions, remembered notes, and instruction files on your machine, reports what it found, and asks which sources you want it to read. 2. **Filter** (sessions only). It writes a filter script that strips tool calls, tool results, attachments, and diffs from the raw transcripts, keeping only the human's prompts and the assistant's prose. The filter runs locally; nothing raw leaves your machine. 3. **Distil.** It reads the filtered output (or the file sources directly) and extracts durable knowledge: how systems actually behave, bugs and their root causes, conventions and the reasoning behind them, corrections to prior beliefs. 4. **Sort.** It separates team knowledge (belongs in shared memory) from personal preferences (belongs in personal memory or stays in your local files). Only team knowledge is a candidate for the workspace. 5. **Show.** It presents a sample of what it would write and waits for your approval. Nothing reaches the workspace until you say so. 6. **Write.** It sends the approved memories to the workspace one source at a time, pacing the writes to avoid rate limits. ### What stays local Your files are never modified. The agent reads them and leaves them exactly as they are. Raw session transcripts are never uploaded, in whole or in part. The agent reads them locally, filters them locally, and distils them locally. Only the finished memories reach the workspace, and only after your approval. ## Why it is safe to re-run The seeding process keeps its state in a working directory at `~/.memco/seed/`. Three markers track progress: - `raw/` means a session has been extracted. It won't be re-extracted. - `memories/.json` means a source has been distilled (an empty `[]` means "looked at, found nothing durable", which is a finished state). - `submitted/` means the memories have been written to the workspace. If a run is interrupted, re-running it picks up where it left off. Nothing is re-extracted, nothing is re-distilled, and nothing is re-sent. The server also recognises memories by content, so even a lost marker cannot produce a duplicate. ## How to trigger it ### Claude Desktop and Cowork Claude Desktop and Cowork surface MCP prompts through their UI. Make sure both the Filesystem connector and Memco Shared Memory are enabled, and that the Filesystem connector has access to the directories where your sessions and instruction files live (typically `~/.claude/`, your project directories, and any editor config folders). Open the prompt picker and select the Memco Shared Memory seed prompt. ### Claude Code, Cursor, Codex, and other agents For agents with filesystem access, ask the agent to fetch the seeding prompt and follow it: ``` Fetch https://spark.memco.ai/prompts/seed-memory.md and follow it. ``` The agent will read the prompt, find your sessions and files, write the extraction filter, distil the knowledge, and stop for your approval before writing anything to the workspace. Claude Code is the most natural environment for seeding sessions: it has direct access to its own session transcripts at `~/.claude/projects/` and can run the filter script directly. ## Scoping the run You can narrow what the seeding process reads: **Which sources.** "Just my sessions", "the notes too", "everything, including the CLAUDE.md files". Instruction files are frequently team-authored and checked into repositories, so the prompt asks before reading them. **How far back.** "The last 30 days", "since June". Only sessions last active within that window are considered. **How many.** "The 20 most recent", "just 5 to start". If both a time window and a count are given, both apply: the newest N within the window. If you don't specify a scope and there are more than about 50 sessions, the agent will suggest a starting scope rather than silently running through hundreds of transcripts. ## What gets saved, and what doesn't The distillation step looks for knowledge that will still be true and useful in six months, to someone who was not there. Good candidates: - How a system actually behaves, especially where it surprised someone - A bug and its root cause - A fix that took real effort to find - A convention or pattern the team follows, and why - A decision and the reasoning behind it - A correction: something believed, found wrong, and put right **Things that are skipped:** anything true only of one branch, one ticket, or one afternoon. Status updates. Generic advice available in any documentation. Anything already obvious from reading the code. **Things that are never saved:** secrets, tokens, API keys, or credentials, regardless of where they appear. ### Team knowledge vs personal preferences The sorting step applies the same test as [personal memory seeding](/personal-memory/seed-your-memory): *if a teammate sat down at their own machine tomorrow, would this still be true for them?* If yes, it belongs in the shared workspace. If it would be true only for one person, on their machine, with their habits, it is a personal preference and the agent leaves it out. If you also have Memco Personal Memory connected, the agent may suggest saving those preferences there instead. ## After seeding The working directory at `~/.memco/seed/` holds the extraction state, the distilled memories, and the submission markers. It is small and worth keeping as a record of what was seeded. The raw session digests under `~/.memco/seed/raw/` are the only part that takes significant space; the agent will offer to delete them once everything is submitted. Every agent connected to your Memco workspace will find the seeded knowledge immediately. The memories are searchable as soon as they are processed (writes are queued and may take a moment to appear). Your workspace content is visible and editable through the [Memco dashboard](https://spark.memco.ai). --- # Tools Reference URL: https://docs.memco.ai/mcp/tools-reference/ Memco exposes eight tools through its MCP interface. ## list_domains Lists the memory domains available to you and describes each one: what it holds, when to search it, what belongs in it and what does not, and the tag vocabulary and format it uses. Call before your first search or write of a task, and whenever you are unsure which domain a question or finding belongs to. The slug returned is what `start_session`, `search`, and `create_memory` take as their `domain` argument. **Parameters:** None. --- ## start_session Starts a session and returns its ID. A session groups the searches you make while working on one task, so they are recorded as a connected series rather than as unrelated one-off calls. Pass the session ID to every `search`, `create_memory`, `enrich_memory`, and `share_feedback` call you make for that task. A session stays usable for as long as you keep naming it. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `domain` | string | yes | The memory domain to operate in. Call `list_domains` for the domains available to you | **Returns:** A session ID. ``` start_session(domain: "coding") → { session_id: "sess_abc123" } ``` --- ## search Searches Memco Shared Memory for existing knowledge before working a problem out from scratch. It holds what your teammates and their agents have already established and recorded. Call when: you start a task, plan a non-trivial piece of work, meet something unfamiliar, hit a question you cannot answer from what you already know, or are about to reason out something a teammate may already have settled. Search first, then work. Pass either a `domain` or a `session_id`. Naming a session runs the search in that session's domain and records it alongside the other searches made for the same task. Naming a domain alone starts a session for that one search. The query uses both keyword and semantic search, and is intended for a single concept per query. If you need varied information, make multiple queries. Results come back most-relevant-first and are bounded; the response says what it left out. Within one session, a result already returned is not repeated — it comes back as a reference to the `idx` that carried it. Use `get_memory` to turn a reference back into content. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `query` | string | yes | A task-based query: a question, statement, or task description. Use markdown formatting for readability | | `session_id` | string | no | The session to record this search under. Supplies the domain, so `domain` is not needed. Omit to start a new session (requires `domain`) | | `domain` | string | no | The memory domain to search in. Required unless `session_id` is provided | | `tags` | array | no | XML tags narrowing subject and context (see [Tag format](#tag-format) below) | Either `domain` or `session_id` must be provided. **Usage:** ``` search( session_id: "sess_abc123", query: "How does the payments service handle retries?", tags: [""] ) ``` --- ## get_memory Fetches the full content of a memory by its `idx`. Call when you hold an `idx` whose content is not in front of you — a search returned the memory as a reference to an earlier result, or another agent passed you the handle. An insight's `idx` returns the memory holding it. Copy the `idx` exactly as it appeared in the search response — it cannot be constructed by hand. When a result shows a `ref` instead of content, fetch by the value in its own `idx`, not the value in the `ref`. The `ref` says where the content was originally delivered, not what to ask for. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `idx` | string | yes | The `idx` from a search result, copied exactly as it appeared | **Returns:** The full memory content. **Usage:** ``` get_memory(idx: "memory-abc123-1") ``` --- ## create_memory Saves new knowledge to Memco Shared Memory, where your teammates and their agents will find it. Call when you have learned something non-obvious that would help your team — why something turned out the way it did, how something actually behaves, something that was hard to establish, or a decision and its rationale — or your user has corrected you. Search first: when a related memory already exists, `enrich_memory` extends it instead of leaving a near-duplicate beside it. Pass either a `domain` or a `session_id`. Naming the session you have been searching in saves the memory into that session's domain and records it as part of that work. Naming a domain alone saves a standalone memory. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `content` | string | yes | The knowledge to save. Should be a concise, non-trivial finding that others can learn from. Supports markdown | | `query` | string | yes | A query describing what someone would search to find this memory — a question or problem statement | | `title` | string | yes | A short title describing what this memory is about | | `session_id` | string | no | The session this memory was learned during. Supplies the domain and records the memory as part of that work. Omit to save a standalone memory (requires `domain`) | | `domain` | string | no | The memory domain to save into. Required unless `session_id` is provided | | `source` | string | no | `"user"` for human-corrected information, `"agent"` for self-discovered insights without human correction | | `tags` | array | no | XML tags describing subject and context (see [Tag format](#tag-format) below) | Either `domain` or `session_id` must be provided. **Returns:** The created memory, including an operation ID that can be passed to `revert_memory` if needed. **Usage:** ``` create_memory( session_id: "sess_abc123", title: "Payments service requires idempotency keys", query: "How to avoid duplicate transactions in the payments service?", content: "The payments service requires idempotency keys on all POST requests. Without them, retries can create duplicate transactions.", source: "agent", tags: [""] ) ``` --- ## enrich_memory Adds information to an existing memory, so your finding lands beside the one it belongs to rather than in a separate memory that competes with it. Call when a search returned a memory close to what you learned but incomplete, out of date, or missing the approach you took. Use `create_memory` instead when nothing returned covers the subject at all. Set `memory_idx` to the memory you want to extend (from the search results), or `"new"` to add a standalone addition. Keep an addition concise and say only what is not already there. The addition lands in the domain the search session ran in. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `content` | string | yes | The knowledge to add. Use markdown formatting. Say only what is not already there | | `memory_idx` | string | yes | The `memory_idx` from a search result, or `"new"` to add a standalone addition | | `session_id` | string | yes | The session ID from a previous search | | `title` | string | yes | A short title describing what you learned | | `source` | string | no | `"user"` for human-corrected information, `"agent"` for self-discovered insights without human correction | | `sources` | array | no | Memory indices from Memco that proved helpful in reaching this insight (up to 20) | | `tags` | array | no | XML tags describing subject and context (see [Tag format](#tag-format) below) | **Returns:** The updated memory, including an operation ID that can be passed to `revert_memory` if needed. **Usage:** ``` enrich_memory( session_id: "sess_abc123", memory_idx: "mem_xyz789", title: "Idempotency key format requirement", content: "The idempotency key must be a UUID v4. The service rejects other formats with a 422 response." ) ``` --- ## share_feedback Rates the relevance and correctness of search results. Only the searching agent can tell whether a result answered the query, and these ratings shape which results are shown next. Call once per search, after reading the results, while the session ID is still to hand. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `session_id` | string | yes | The session ID from the search being rated | | `feedback` | array | yes | A list of feedback entries in XML format (up to 10 per call) | Each feedback entry is an XML tag: ``` optional comment ``` The `idx` is copied exactly as it appears in the search response — it cannot be constructed by hand. Set `relevant` to `true` if the result was a good match for the query, and `correct` to `true` if the content was accurate. Use an insight's `idx` for a specific insight, or a memory's own `idx` to apply feedback to every insight under it. **Usage:** ``` share_feedback( session_id: "sess_abc123", feedback: [ "Exactly what I needed", "" ] ) ``` --- ## revert_memory Undoes a memory you just wrote — wrong content, wrong domain, or something that should not have been shared. Your entry is always removed. The memory it belongs to is removed with it only when your entry was the last one in it — so reverting a `create_memory` (or an `enrich_memory` sent with `memory_idx` `"new"`) removes that memory too, while reverting an addition to a memory that holds other entries leaves the memory in place. You can only revert your own writes, and only within 2 days. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `op_id` | string | yes | The operation ID returned by `create_memory` or `enrich_memory` | **Usage:** ``` revert_memory(op_id: "create-hpc08-1") ``` --- ## Tag format Tags use XML format with a `type`, `name`, and optional `version`: ``` ``` The tag types available and their semantics are domain-specific. Call `list_domains` to see which tag types each domain uses and which of them accept a version. Supply as many tags as you can determine for the best results. Tags can be passed to `search`, `create_memory`, and `enrich_memory`. In search, they narrow results to matching knowledge. In creation and enrichment, they classify the knowledge for future retrieval. ## Typical session flow 1. **`list_domains`** — discover available domains and their semantics 2. **`start_session`** — begin a session in the relevant domain 3. **`search`** — find relevant knowledge for the current task 4. **`share_feedback`** — rate the search results 5. **`create_memory`** / **`enrich_memory`** — contribute new knowledge back Steps 3–5 repeat throughout the session. The agent passes the session ID to each call; Memco handles persistence and trust scoring. --- # Personal Memory URL: https://docs.memco.ai/personal-memory/overview/ Memco Personal Memory stores your individual preferences, working style, and context in a single place that every AI agent you use can access. Switch between Claude, ChatGPT, Cursor, or any other MCP-compatible client and your agents already know how you work. Personal memory is private to you. No one else in your organisation can see it, and it is stored separately from your team's shared memory. ## How it relates to Shared Memory Memco offers two complementary memory products: - **Shared Memory** holds what your team should know: validated solutions, operational decisions, institutional knowledge. It is the core Memco product, with trust scoring, multi-agent learning, and governed curation. [Learn more about Shared Memory.](/mcp/overview) - **Personal Memory** holds what is yours: how you like responses formatted, your editor setup, your role, your working context. Both are accessed via MCP and managed through the same Memco dashboard at [memco.ai](https://memco.ai). You can use one or both. ## Endpoint ``` https://spark.memco.ai/mcp-personal ``` This is separate from the Shared Memory endpoint (`https://spark.memco.ai/mcp`). Each agent connection needs to be configured for the endpoint it will use. An agent can connect to both. ## Authentication Personal Memory uses OAuth 2.0 for authentication, the same flow as Shared Memory. When an MCP client connects for the first time, it redirects you to sign in and authorise the connection. Subsequent connections reuse the stored credentials. For programmatic access, API keys are available through the Memco dashboard. ## Getting started ### Coding agents: install the plugin In Claude Code, Codex and Cursor the fastest route is the `personal-memory@memco` plugin from the Memco marketplace. It registers the Personal Memory MCP server and installs the agent instructions in one step. ``` /plugin marketplace add memcoai/marketplace /plugin install personal-memory@memco ``` ``` codex plugin marketplace add memcoai/marketplace codex plugin add personal-memory@memco ``` In Cursor, add `memcoai/marketplace` under **Settings → Plugins → Team Marketplaces** and install **memco-personal-memory** from the marketplace panel. If you also use Shared Memory, install `shared-memory@memco` alongside it. The two plugins connect to different servers and do not interfere with each other. ### Assistants: connect the server #### Step 1: Add the MCP server Add the Memco Personal Memory MCP server through your assistant's MCP or integrations settings. **Claude and Claude Desktop** — go to **Settings → Connectors** and add the **Memco Personal Memory** connector from the directory, or add it as a custom connector with the endpoint above. **Claude Desktop, manual configuration** — add the following to your `claude_desktop_config.json`: ```json { "mcpServers": { "memco-personal-memory": { "url": "https://spark.memco.ai/mcp-personal" } } } ``` **Cursor** — add to your MCP settings in `.cursor/mcp.json`: ```json { "mcpServers": { "memco-personal-memory": { "url": "https://spark.memco.ai/mcp-personal" } } } ``` **Claude Code** — add from the command line: ```bash claude mcp add memco-personal-memory --transport streamable-http https://spark.memco.ai/mcp-personal ``` #### Step 2: Instruct your agent to use it Adding the MCP server makes the tools available, but your agent also needs to know it should use them. Add the following to your project instructions, custom instructions, or system prompt: ``` You have access to a personal memory server through the Memco Personal Memory MCP server. Use that to store and recall my preferences, working style, and personal context across sessions. ``` Where to put this depends on your assistant: - **Claude** — add to your project instructions, or to **Settings → Profile → User preferences** for it to apply across all conversations - **ChatGPT** — add to **Personalisation → Custom Instructions** - **Cursor** — add to your project-level rules or `.cursorrules` file #### Step 3: Verify the connection Ask your agent: > "What do you know about my preferences?" If the connection is working, the agent will call `start_session` and report back what it finds. On a fresh account, it will say there are no saved preferences yet. ## Tool surface Memco Personal Memory provides seven MCP tools: | Tool | Purpose | |---|---| | `start_session` | Load your preferences and tag overview at the start of a conversation | | `search` | Find memories by semantic query | | `list_memories` | Browse all memories, with optional keyword and tag filters | | `get_memory` | Fetch the full content of a memory by its ID | | `write_memory` | Save a new memory | | `update_memory` | Edit part of an existing memory in place | | `delete_memory` | Permanently remove a memory | See the [Tools Reference](/personal-memory/tools-reference) for the complete specification of each tool. ## How agents use the tools A typical session: 1. **Start.** The agent calls `start_session` at the beginning of a conversation. This returns a summary of your stored preferences (memories tagged `type:user`) and the tags in use, giving the agent immediate context about how you work. 2. **Recall.** When the agent needs to check a preference or piece of context, it calls `search` with a query, or `list_memories` to browse. 3. **Learn.** When you share a new preference or the agent discovers one through the conversation, it calls `write_memory` to save it. 4. **Update.** When a preference changes, the agent calls `update_memory` to edit it in place rather than creating a duplicate. 5. **Forget.** When you ask the agent to forget something, it calls `delete_memory`. Deletion is permanent. ## Managing your memories All your personal memories are visible and editable through the Memco dashboard at [memco.ai](https://memco.ai). You can view, edit, and delete individual memories at any time. The dashboard gives you full control over what your agents remember about you. --- # Seed Your Memory URL: https://docs.memco.ai/personal-memory/seed-your-memory/ Personal memory is empty until something is put in it. But if you already use AI coding agents or assistants, you have probably written your preferences down somewhere: a `CLAUDE.md` file, a `.cursorrules`, custom instructions in ChatGPT, or the remembered notes your agent has accumulated over time. The seeding process extracts personal preferences from those sources and writes them into your Memco Personal Memory, where every agent you use can access them. You run it once. It takes a few minutes. ## What it does Seeding walks through three stages: 1. **Find.** The agent locates instruction files and remembered notes on your machine and asks which sources you want it to read. 2. **Sort.** It reads the sources you chose and separates personal preferences (how you like things done) from team rules (how the project works). Team rules stay where they are. Only personal preferences are candidates for your memory. 3. **Write.** It shows you the full list of what it would save and waits for your approval. Nothing reaches personal memory until you say so. Your files are never modified. The agent reads them and leaves them exactly as they are. Removing a preference from its source file is your decision, and the agent will offer (never act) after the seeding is complete. ## Why it is safe to re-run Every memory carries an `external_id` derived from the preference it describes. Writing the same `external_id` again replaces the memory rather than creating a duplicate. So an interrupted or repeated run converges rather than accumulating copies. There is no state to clean up afterwards. ## How to trigger it ### Claude Desktop and Cowork Claude Desktop and Cowork surface MCP prompts through their UI. Make sure both the Filesystem connector and Memco Personal Memory are enabled, and that the Filesystem connector has access to the directories where your instruction files live (typically `~/.claude/`, your project directories, and any editor config folders). Open the prompt picker and select the Memco Personal Memory seed prompt. The agent will search the accessible directories for instruction files and remembered notes, then follow the same find-sort-approve flow. ### Claude Code, Cursor, Codex, and other agents For agents with filesystem access, ask the agent to fetch the seeding prompt and follow it: ``` Fetch https://spark.memco.ai/prompts/seed-personal-memory.md and follow it. ``` The agent will read the prompt, find your instruction files and remembered notes, sort personal preferences from team rules, and stop for your approval before writing anything. To restrict to remembered notes only (skipping instruction files that may be team-authored), add that to your request. ### ChatGPT ChatGPT does not have filesystem access to your machine. If your MCP client supports MCP prompts, select the seed prompt and the agent will ask you to paste or upload your instruction files. Otherwise, paste your preferences into the conversation and ask: ``` Here are my current preferences and instructions. Extract the personal ones and save them to my personal memory. ``` ## What gets saved, and what doesn't The sorting step applies one test to every line it reads: *if a teammate sat down at their own machine tomorrow, would this still be true for them?* If yes, it is a team rule and stays where it is. If it would be true only for you, on your machine, with your habits and your preferences, it belongs in personal memory. **Examples of personal preferences:** how you want code changes presented, your preferred spelling conventions, how much autonomy you grant the agent (e.g. "don't commit without asking"), your editor setup, your formatting preferences. **Examples of team rules that stay put:** how to run the test suite, which branches to use, architectural constraints, environment setup instructions that apply to everyone on the project. **Things that are never saved:** secrets, tokens, API keys, or credentials, regardless of where they appear. Anything tied to a specific ticket, branch, or short-lived context. Advice generic enough to appear in any documentation. Quality matters more than volume. Ten preferences that actually change how an agent behaves are worth more than sixty that dilute every session's startup load. ## After seeding Once seeding is complete, every agent connected to your Memco Personal Memory will pick up the preferences at the start of its next session. There is nothing else to configure. Your preferences are visible and editable in the [Memco dashboard](https://spark.memco.ai). You can review, edit, or delete any memory at any time. --- # Personal Memory Tools Reference URL: https://docs.memco.ai/personal-memory/tools-reference/ Memco Personal Memory exposes seven tools through its MCP interface. ## start_session Loads your identity and preferences at the start of a conversation. Returns memories tagged `type:user` as one-line hooks (title and description), along with a summary of all tags in use. Call this at the beginning of every conversation to give the agent immediate context about the user's preferences and working style. The hooks returned are summaries, not full content. Call `get_memory` with the `external_id` shown in the listing to retrieve the full note. **Parameters:** None. **Returns:** A listing of preference hooks and tags in use. ``` start_session() → # Your preferences (type:user) - Preferred spelling convention for written content. (spelling-preference) — updated 2026-09-02 - Preferred code style and formatting. (code-style) — updated 2026-08-28 # Tags in use - type:user (2) ``` --- ## search Searches your personal memories by semantic query. Returns full memory content for matching results. Call when you need to find a specific preference or piece of context but do not know its `external_id`. Use `list_memories` instead when you want to browse all memories or filter by keyword or tag. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `query` | string | yes | A natural language query describing what you are looking for | **Returns:** Matching memories with their full content, `external_id`, and last-updated date. **Usage:** ``` search(query: "spelling convention preference") → ## Spelling preference (spelling-preference) — updated 2026-09-02 User prefers British English spelling in all documents. ``` --- ## list_memories Lists your personal memories, newest first. Pass `keyword` to filter by substring match on title or content, `tags` to filter by tag, or `page` and `page_size` to paginate. Call when you want to see everything saved, or to find the `external_id` of a memory you intend to read, update, or delete. Use `search` instead when you know what you are looking for semantically. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `keyword` | string | no | Only list memories whose title or content contains this text (case-insensitive substring match) | | `tags` | array | no | Filter by tags. See [Tag format](#tag-format) below | | `page` | integer | no | Page to return (1-based, default 1) | | `page_size` | integer | no | Memories per page (default 25, max 100) | **Returns:** A list of memories as `external_id: title`. **Usage:** ``` list_memories(keyword: "spelling") → spelling-preference: Spelling preference ``` --- ## get_memory Fetches one personal memory in full by its `external_id`. Returns the title, content, and last-updated date. Call when `start_session` or `list_memories` showed you an `external_id` whose full content you now need. Those listings carry only a one-line hook; this tool returns the complete note. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `external_id` | string | yes | The `external_id` of the memory to retrieve | **Returns:** The full memory content. **Usage:** ``` get_memory(external_id: "spelling-preference") → # spelling-preference — updated 2026-09-02 Spelling preference User prefers British English spelling in all documents. ``` --- ## write_memory Saves a new note to your personal memory. Use for durable, private preferences: how you like responses formatted, your editor and workflow settings, personal facts, or working context. One preference per memory. Keep memories focused and atomic so they are easy to find, update, and delete independently. Supply a stable `external_id` to name the memory. Re-writing the same `external_id` replaces the note entirely, so use `update_memory` when only part of it should change. Add a one-line `description` — it is the hook shown in your `start_session` listing and what semantic search matches on. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `title` | string | yes | A short title, shown in listings | | `content` | string | yes | The knowledge to save. Keep these short, under 5000 characters | | `description` | string | no | A one-line description — the hook shown in your startup listing and used to find the memory | | `external_id` | string | no | A stable name for this memory. Re-writing the same `external_id` replaces it. Generated when omitted | | `tags` | array | no | Tags to organise the memory. See [Tag format](#tag-format) below | **Returns:** Confirmation with the assigned `external_id`. **Usage:** ``` write_memory( title: "Spelling preference", content: "User prefers British English spelling in all documents.", description: "Preferred spelling convention for written content.", external_id: "spelling-preference", tags: [""] ) → Saved to your personal memory as "spelling-preference". update_memory edits part of it in place. ``` --- ## update_memory Edits an existing personal memory in place. You can replace a substring of the content (`old_string` → `new_string`), prepend or append text, and change the title or description. Untouched fields and tags are preserved. Call when a preference has changed or needs a detail added and the rest of the note should survive. Use `write_memory` with the same `external_id` when the whole note should be replaced. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `external_id` | string | yes | The `external_id` of the memory to edit | | `old_string` | string | no | Exact text in the content to replace. Must appear exactly once unless `replace_all` is set | | `new_string` | string | no | Replacement for `old_string`. Omit to delete the matched text | | `replace_all` | boolean | no | Replace every occurrence of `old_string` instead of erroring when it appears more than once | | `prepend` | string | no | Text to insert at the very start of the content | | `append` | string | no | Text to insert at the very end of the content | | `title` | string | no | Replace the title | | `description` | string | no | Replace the one-line description | **Returns:** Confirmation that the memory was updated. **Usage:** ``` update_memory( external_id: "spelling-preference", append: " Exception: use American English for documents intended for US audiences." ) → Updated your personal memory "spelling-preference". get_memory returns it in full if you want to read back the result. ``` --- ## delete_memory Permanently deletes one personal memory by its `external_id`. There is no undo. Call when a saved preference is wrong or no longer true and no edit would fix it. Prefer `update_memory` when the note should change rather than disappear. **Parameters:** | Parameter | Type | Required | Description | |---|---|---|---| | `external_id` | string | yes | The `external_id` of the memory to delete | **Returns:** Confirmation that the memory was deleted. **Usage:** ``` delete_memory(external_id: "spelling-preference") → Deleted personal memory "spelling-preference". Deletion is permanent — there is no undo. ``` --- ## Tag format Tags use XML format with a `type` and a `value`: ``` ``` The most important tag is `type:user`, which marks a memory as a user preference. Memories with this tag appear in the `start_session` listing, giving agents immediate access to your core preferences at the start of every conversation. Use `scope` tags to partition memories by context (e.g. `work`, `personal`, `project-name`). This is optional but can help keep memories organised as the collection grows. --- # SDK Overview URL: https://docs.memco.ai/sdk/index/ The Memco SDKs give your own code the same memory operations that MCP gives an off-the-shelf agent. Use them when you are building the agent, the pipeline, or the product yourself and want memory as a component of it. | Language | Package | Install | Reference | |---|---|---|---| | Python | `memcoai` | `pip install memcoai` | [/sdk/python/latest](/sdk/python/latest) | | Node.js | `@memco/memcoai` | `npm install @memco/memcoai` | [/sdk/nodejs/latest](/sdk/nodejs/latest) | | Go | `github.com/memcoai/memcoai/go/memcoai` | `go get github.com/memcoai/memcoai/go/memcoai` | [/sdk/go/latest](/sdk/go/latest) | All three packages are open source under the MIT license at [github.com/memcoai/memcoai](https://github.com/memcoai/memcoai). The Go module requires Go 1.25 or newer. You need a Memco account and an API key, created from the [Memco dashboard](https://spark.memco.ai). ## SDK, MCP, or CLI? **MCP** is the right choice when the agent already exists and you want it to use Memco: Claude, ChatGPT, Cursor, Claude Code, and any other MCP-compatible client. You configure a connection and the agent does the rest. See the [MCP overview](/mcp/overview). **The SDK** is the right choice when you own the code that drives the agent loop, or when there is no agent at all. Typical cases: - An agent you built with LangChain, the Anthropic SDK, the OpenAI SDK, or your own loop, that should search memory before working and write back what it learned. - A product you ship to your own customers, where memory is part of what the product does. See [Embedding memory in your product](/sdk/embedding-memory). - Data pipelines: seeding a memory network from existing documents, exporting it, or running evaluations against it. - Administrative tooling and integrations that call the API without a model in the loop. **The CLI** covers interactive and scripted use from a terminal. See [CLI installation](/cli/installation). All three surfaces talk to the same service, with the same domains and the same operations. Which memory a call can reach is decided by the network permissions of the user it is made for, not by which surface made it: an MCP-connected engineer and an SDK-driven agent serving one of your customers see the networks they have each been granted, and nothing else. ## What the SDKs provide The SDKs wrap the Memco API with the same design, so a team working in more than one language finds the same shape on each side. **Every memory operation.** `list_domains`, `start_session`, `search`, `get_memory`, `create_memory`, `enrich_memory`, `share_feedback`, `revert_memory`, and `import_memories`. These are the operations the [MCP tools](/mcp/tools-reference) expose, with the same semantics. **Sessions that cannot be dropped.** A session groups the searches made for one task, so they can be rated together and so the service can relate them. `start_session` returns a session object with every session-bound operation already applied. Once bound, no later call can omit the session id. This matters more than it looks: a search that silently drops the id is still a valid search, it just stops being part of the series, which is the kind of mistake an agent makes and nobody notices. **Agent tools in the service's own words.** A session exports its operations as a toolset for LangChain, the Anthropic SDK, and the OpenAI SDK. The Go SDK exports Anthropic and OpenAI tool shapes; it has no LangChain adapter. The description a model reads for each tool comes from the same manifest the hosted MCP server publishes, so an agent built on the SDK is steered by the service's guidance rather than by wording that lives in the client. See [Building an agent with the SDK](/sdk/building-an-agent). **Typed results and typed errors.** Results are typed objects. Every failure is a subclass of a single base error (in Go, a concrete type implementing `memcoai.Error`, matched with `errors.As`), with specific classes for authentication, permission, invalid requests, rate limits, timeouts, and service availability, so no transport-level exception reaches your code. **Networks and users.** A client authenticated as an API client manages your memory networks and the users of your product, and opens sessions that act for one of those users. See [Embedding memory in your product](/sdk/embedding-memory). **Local validation.** On connection the client fetches the input limits the service enforces and applies them locally. An oversized field is refused before a request is sent. **Idiomatic in each language.** Python ships `Memco` and `AsyncMemco` with identical method names. Node.js is async throughout and supports `await using` for automatic cleanup, with ESM and CommonJS builds. Go takes a `context.Context` on every blocking call for cancellation and deadlines, and a client and its sessions are safe for concurrent use. ## Quick start ### Python ```python from memcoai import Memco with Memco() as client: # reads MEMCO_API_TOKEN session = client.memory.start_session("coding") result = session.search("how should a client authenticate against the memory API") for memory in result.memories: for insight in memory.insights: print(insight.title, insight.updated) ``` ### Node.js ```typescript import { Memco } from '@memco/memcoai' await using client = await new Memco().connect() // reads MEMCO_API_TOKEN const session = await client.memory.withSession('coding') const result = await session.search( 'how should a client authenticate against the memory API' ) for (const memory of result.memories) { for (const insight of memory.insights) { console.log(insight.title, insight.updated) } } ``` ### Go ```go ctx := context.Background() client, err := memcoai.NewClient(memcoai.Options{}) // reads MEMCO_API_TOKEN if err != nil { return err } defer client.Close(ctx) if err := client.Connect(ctx); err != nil { return err } session, err := client.Memory.StartSession(ctx, "coding") if err != nil { return err } result, err := session.Search(ctx, "how should a client authenticate against the memory API", memcoai.ScopedSearchParams{}) if err != nil { return err } for _, memory := range result.Memories { for _, insight := range memory.Insights { fmt.Println(insight.Title, insight.Updated) } } ``` ## Configuration All three SDKs read their configuration from the environment, with constructor arguments (in Go, `memcoai.Options` fields) taking precedence. | Setting | Environment variable | Default | |---|---|---| | Credential | `MEMCO_API_TOKEN` | required, unless API client credentials are given | | API client id | `MEMCO_CLIENT_ID` | none | | API client secret | `MEMCO_CLIENT_SECRET` | none | | Endpoint | `MEMCO_API_HOST` | `grpc.memco.ai:443` | | Log level | `MEMCO_LOG` | `info` | The credential is a Memco API key from the dashboard. `MEMCO_API_KEY` is still honored but logs a warning; switch to `MEMCO_API_TOKEN`. An API client's id and secret are used together, and the SDK exchanges them for a token that it renews for as long as the client is open. When both a token and client credentials are set in the environment, the client credentials win. A client authenticated this way manages networks and users, and reaches memory through sessions that act for the users of your product; see [Embedding memory in your product](/sdk/embedding-memory). ## Runnable examples Each package ships a set of runnable programs, smallest first: connect and search, the full search-and-rate loop, contributing and reverting, bulk import, error handling, concurrent searches, mapping a customer's organization into networks and users, acting for the users of your product, and a complete LangChain agent. - [Python examples](https://github.com/memcoai/memcoai/tree/main/python/examples) - [Node.js examples](https://github.com/memcoai/memcoai/tree/main/nodejs/examples) - [Go examples](https://github.com/memcoai/memcoai/tree/main/go/examples) (a complete Anthropic SDK agent in place of LangChain) ## Versioning The reference documentation is published per version. `/sdk/python/latest`, `/sdk/nodejs/latest`, and `/sdk/go/latest` always point at the current release; earlier releases stay available at their own version paths. Each package records the version of the service contract it was built from, and the service tells a client when the version it is running is superseded. ## Next steps - [Building an agent with the SDK](/sdk/building-an-agent) — the learning loop, the toolset export, and the patterns that make memory work in an agent you control - [Embedding memory in your product](/sdk/embedding-memory) — memory networks, the users of your product, and how memory becomes part of what you ship - [Python reference](/sdk/python/latest), [Node.js reference](/sdk/nodejs/latest), and [Go reference](/sdk/go/latest) - [Learning on the Job](/examples/learning-on-the-job) — a measured example of an agent learning from reviewer corrections --- # Building an Agent with the SDK URL: https://docs.memco.ai/sdk/building-an-agent/ This guide is for the case where you own the agent loop: you chose the model, you wrote the prompt, and you decide which tools it gets. It shows how to add Memco Shared Memory to that agent so it searches before working and writes back what it learned. The code is Python. The Node.js SDK has the same shape with the same names in camelCase; see the [Node.js reference](/sdk/nodejs/latest). ## The loop An agent with memory does three things it did not do before: 1. **Search before working.** Given a task, it searches the domain for what teammates and their agents have already established. 2. **Rate what it was given.** After using a result, it reports whether the result was relevant and correct. Ratings are what move the reliability signal on a memory, so an agent that never rates is an agent whose memory never improves. 3. **Write back what it learned.** When it establishes something non-obvious, it saves it: why something turned out the way it did, how a system actually behaves, a decision and its rationale. Everything else on this page is about making those three steps reliable when a model is the one deciding when to take them. ## Handing the tools to a model A session exports its operations as a toolset. The toolset carries what a model needs beyond the calls themselves: a description of each tool, a JSON Schema for its arguments, results rendered as text, and the handover to whatever is driving the loop. ```python from memcoai import Memco, agent with Memco() as client: entry = next(d for d in client.memory.list_domains().domains if d.slug == "coding") with client.memory.with_session("coding") as session: toolset = session.tools() system_prompt = agent.briefing(entry, session.instructions) # hand toolset and system_prompt to your framework of choice ``` The same toolset speaks three shapes: ```python # LangChain runnable = create_agent(model, tools=toolset.to_langchain(), system_prompt=system_prompt) # Anthropic SDK, driving the loop yourself response = anthropic.messages.create(tools=toolset.to_anthropic(), ...) text_for_model = toolset.call(block.name, block.input) # OpenAI SDK, driving the loop yourself completion = openai.chat.completions.create(tools=toolset.to_openai(), ...) text_for_model = toolset.call(call.function.name, call.function.arguments) ``` `toolset.call` runs the operation the model asked for and returns text the model can read. `to_langchain` needs LangChain installed; the other two produce plain data and need nothing. ## Three choices the SDK makes for you **The session is bound in code, outside the loop.** Every tool in the toolset is bound to the session it was built from. The model never sees a session id and cannot omit or invent one, so every call it makes is recorded as part of the same series. If you build the tools by hand instead, a model that drops the id produces a search that still succeeds and is silently unrelated to the task. **Domain guidance goes in the system prompt, not behind a tool.** `list_domains` returns, for each domain, what it holds, when to search it, what belongs in it, and the tag vocabulary. `agent.briefing()` renders that answer into text for the system prompt. A tool the model may forget to call is a tool that does not steer it, so the toolset exposes neither `list_domains` nor `start_session`. **The tool descriptions are the service's.** The text a model reads for each tool comes from the same manifest the hosted MCP server publishes. When the service changes its guidance, the change reaches your agent with an SDK release rather than diverging silently. Three parameters keep SDK-specific wording because they are typed objects here and XML strings over MCP: `tags`, `feedback`, and `source`. ## What the model sees when things go wrong Not every failure should reach the model. A malformed request, an invented tool name, or a handle that resolves to nothing are things a model can fix on its next turn, so these come back as text. A rejected credential, a rate limit, or an unreachable service are things no wording will fix, so these are raised to your code. `agent.AGENT_RECOVERABLE` is the set of error classes that go back to the model; everything else propagates. ## Patterns that make memory work These come from building agents on Memco, including the [Learning on the Job](/examples/learning-on-the-job) experiments. **Fix the topic per project; do not let the model choose it.** Left free, each write invents its own taxonomy (`returns`, `shipping-issues`, `customer-policy`) and lessons filed under one made-up topic stop being found by searches scoped to another. The failure presents as retrieval misses rather than as a tagging problem, which makes it hard to diagnose. Set the tags at the integration layer and keep them constant for the whole corpus. **Search at the start of every task, not once per process.** Memory changes while the agent runs, and the search that matters is the one made with the task in hand. **Rate after use, not after retrieval.** A result looks relevant at retrieval time and turns out wrong in use. The useful signal comes after the agent has acted on it. **Write findings, not transcripts.** A memory should be a concise, non-trivial finding someone else can act on. Raw trajectories transfer badly between tasks. **Keep the write path reversible.** `create_memory` returns an operation id. Keep it while the agent's work is still under review, so a write that turns out wrong can be undone with `revert_memory` inside the revert window. ## A complete example [`langchain_agent.py`](https://github.com/memcoai/memcoai/blob/main/python/examples/langchain_agent.py) is a complete agent in about eighty lines, using only what the SDK supplies. It runs against any provider LangChain supports: ```bash export MEMCO_API_TOKEN=... uv run --with memcoai --with langchain --with langchain-google-genai \ python examples/langchain_agent.py ``` The Node.js equivalent is [`langchain_agent.ts`](https://github.com/memcoai/memcoai/blob/main/nodejs/examples/langchain_agent.ts). ## Next steps - [Embedding memory in your product](/sdk/embedding-memory) — when the agent is part of something you ship to your own customers - [Trust](/concepts/trust) — how ratings become reliability signals - [Knowledge domains](/concepts/knowledge-domains) — what each domain holds and how tags work --- # Embedding Memory in Your Product URL: https://docs.memco.ai/sdk/embedding-memory/ The SDK lets you build memory into something you sell. Your customers use your product; your product uses Memco; each of your customers gets agents that learn how their organization works, and none of them sees another's memory. ## Who is who Three parties are involved, and it helps to name them. - **You** are the Memco customer: the vendor building the product. Your own staff have Memco accounts and authenticate with Memco directly. - **Your customers** are organizations using your product. They have no relationship with Memco. - **The users of your product** are the people at your customers who use it. They authenticate with you, using whatever identity system your product already has. Your product calls Memco through the SDK, on behalf of the users of your product. ## Memory networks A memory network is a group of people and agents that learn together. Everyone placed in a network searches and contributes to the same memory; nobody outside it can see in. Your own staff have networks of their own for the `coding` and `knowledge` work of building your product. What you create for your customers is separate. Networks form a hierarchy. A network reads from every network above it, and writes stay in the network they were made in. You arrange networks to match each customer: **One network per customer.** The simplest case. Each customer's agents learn from that customer's users and nobody else. What one customer's team corrects, every agent serving that team benefits from; a second customer starts from its own baseline. **As many networks as a customer's structure needs.** A customer with teams, projects or product lines that each need their own memory gets a network for the customer and one under it for each part. People placed in a project see that project's knowledge and the customer's, and never another project's. People placed in the customer network see only what the whole customer shares. **A parent network you maintain.** A network holding what every customer should start with: how your product works, good practice for the domain, policies that apply to everyone. Each customer's network sits under it and reads from it. A customer's corrections shape their own network and never flow back into what other customers read. **A shared network across customers.** For products where the knowledge is common by design, such as a tool whose users all work on the same public standard, users from several customers can be placed in one network. A parent network is how you deliver initial knowledge. Instead of a blank memory on day one, each customer's agents start with your accumulated understanding of the domain and add their own. Each network belongs to one memory domain, and a user is placed in one network per domain. That network is where their writes go; everything above it is what they can also read. ## Managing networks and users Network and user management needs an **API client**: a credential for your backend, with the `network-management` and `user-management` scopes, and the admin grant to act for your users. Give the SDK its id and secret, as arguments or as `MEMCO_CLIENT_ID` and `MEMCO_CLIENT_SECRET`, and it exchanges them for a token and renews it for as long as the client is open. The users of your product are represented in Memco as **external users**: users you own and authenticate, known to Memco by your own id for them. Memco never sees their credentials; your systems do. An external user has no sign-in of its own, never holds `admin`, and can be placed only in a network created with `scope="customer"`. ### Python ```python from memcoai import Memco with Memco(client_id="...", client_secret="...") as client: root = client.networks.list(parent_id="root", domain="knowledge").networks[0] acme = client.networks.create(name="Acme", parent_id=root.id, scope="customer") payroll = client.networks.create(name="Acme / Payroll", parent_id=acme.id, scope="customer") user = client.users.create("acme-ada", roles=["reader", "creator"], name="Ada") client.networks.add_member(payroll.id, user.id) ``` ### Node.js ```typescript import { Memco } from '@memco/memcoai' await using client = await new Memco({ clientId, clientSecret }).connect() const [root] = (await client.networks.list({ parentId: 'root', domain: 'knowledge' })).networks const acme = await client.networks.create({ name: 'Acme', parentId: root.id, scope: 'customer' }) const payroll = await client.networks.create({ name: 'Acme / Payroll', parentId: acme.id, scope: 'customer' }) const user = await client.users.create('acme-ada', { roles: ['reader', 'creator'], name: 'Ada' }) await client.networks.addMember(payroll.id, { userId: user.id }) ``` A child network takes its domain from its parent. Placing a user who is already in another network of the same domain is refused, naming that network, unless you ask for the move (`force=True` in Python). Deleting a network deletes everything placed in it. The [Python](https://github.com/memcoai/memcoai/blob/main/python/examples/map_your_users.py) and [Node.js](https://github.com/memcoai/memcoai/tree/main/nodejs/examples) examples map a consulting company, its client projects and its engineers into networks in full, and remove them again at the end. ## Acting for the users of your product When a user works in your product, your backend opens a session that acts as them, by passing your id for them: ```python with Memco(client_id="...", client_secret="...") as client: with client.memory.with_session("knowledge", external_id="acme-ada") as session: result = session.search("how do we handle refunds for annual plans") ``` ```typescript await using session = await client.memory.withSession('knowledge', { externalId: 'acme-ada' }) const result = await session.search('how do we handle refunds for annual plans') ``` The SDK has the service issue a short-lived key for that user, renews it in the background, and ends it when the session closes. Every call made through the session, including the tools it exports to an agent, carries that key and never your client's token. What the session can find is what that user may find, and what it writes is theirs. Sessions for different users run side by side on one client. Close sessions when the work is done. The service caps how many live keys each user may hold, and a session left open holds one until its key expires. If one of your users needs their own agent to reach Memco directly over MCP, issue them a key with `users.create_key`. Its value is returned once and never again. Because contributions carry the identity of the user who made them, the [trust model](/concepts/trust) works the same way it does for your own staff: a user whose insights are consistently rated well earns standing in their network, and a correction from a domain expert carries more weight than a guess. ## The learning loop, at the product level Inside your product, the agent follows the same loop as any other agent built on the SDK: search the customer's network before working, act, rate what it used, write back what it learned. See [Building an agent with the SDK](/sdk/building-an-agent). What changes at the product level is where the corrections come from. In most products two audiences interact with the agent: the people asking for something, and the experts who know how things actually work at that organization. When the agent is unsure, it escalates to the expert; when the expert answers, that answer becomes an insight. The next time a similar question arrives, it is self-serve. Over weeks the share of questions the agent handles on its own rises, and the experts spend their time on the questions that need them. Two mechanisms keep this from becoming a pile of unverified assertions. Every insight carries a reliability signal built from how it was rated in use, and a low signal is a reason to escalate rather than to answer. And every write is reversible within a window, so an expert who spots a wrong insight can remove it before it spreads. Networks are governed by default through trust and validation rules, with human review where you require it. ## Seeding a network A new customer's network can be filled before their first session, from documents and structured knowledge they already have: a data dictionary, a policy handbook, an internal wiki. `import_memories` contributes many insights in one call. Each is evaluated on the way in and carries the standing of whoever contributed it, so imported knowledge is ordinary knowledge rather than a privileged layer that cannot be corrected. Knowledge every customer should start with belongs in a parent network instead, so you maintain it once. ## Data residency and isolation Every network is stored in the region configured for it (the `region` argument when it is created), and requests are routed to that region regardless of the endpoint your backend connects to. Network isolation is enforced at the service: a key acting for one user reaches only the networks that user is placed in and the networks above them. ## Next steps - [SDK overview](/sdk): install, configure, and the operations available - [Building an agent with the SDK](/sdk/building-an-agent) - [Trust](/concepts/trust): how reliability signals are built and why they matter for escalation --- # CLI Installation URL: https://docs.memco.ai/cli/installation/ The Spark CLI provides command-line access to the Spark knowledge network. It powers the coding agent plugins and can also be used directly for scripted operations, CI/CD integrations, and command-line workflows. ## Install via plugin (recommended) The recommended way to install Spark is through the Memco plugin marketplace, which sets up both the CLI and agent integration in one step. See the [Quickstart](/quickstart) for plugin installation instructions for Claude Code, Codex, and Cursor. ## Install the CLI directly If you prefer to install the CLI on its own: ```bash # Quick install curl -fsSL https://raw.githubusercontent.com/memcoai/spark-cli/main/install.sh | bash # Or via npm npm install -g @memco/spark ``` ## Authentication Spark supports multiple authentication methods. When more than one is configured, they resolve in this order: CLI flag, environment variable, OAuth token, legacy API key. ### OAuth login (recommended) ```bash # Interactive login — opens your browser spark login # Store credentials in the current directory instead of globally spark login --local # Check who you're logged in as spark whoami # Log out spark logout ``` Credentials are saved to `~/.spark/settings.json` (global) or `./.spark/settings.json` (with `--local`). ### Environment variable (recommended for CI/automation) ```bash export SPARK_API_KEY=sk_... spark query "error message" ``` ### CLI flag Pass an API key for a single invocation without storing it: ```bash spark --api-key sk_... query "error message" ``` Visit [spark.memco.ai/dashboard](https://spark.memco.ai/dashboard) to generate an API key. ## Initialization After installation, initialize Spark for your IDE: ```bash spark init ``` `spark init` detects whether your account is public or Teams, installs the matching plugin from the marketplace, and adds the Spark skills for the IDEs you select. To enable Spark for a specific project, run from that project's directory: ```bash spark enable ``` To disable Spark for the current project: ```bash spark disable ``` ## Output format All output is JSON by default, which is easy for AI agents to parse: ```bash spark query "error" # {"session_id":"abc123","recommendations":[...]} ``` Use `--pretty` for human-readable output: ```bash spark --pretty query "error" ``` --- # CLI Commands URL: https://docs.memco.ai/cli/commands/ All commands are invoked as `spark `. Output is JSON by default; use `--pretty` for human-readable formatting. ## Setup commands | Command | Description | |---|---| | `spark init` | Detect account type, install the matching plugin, and configure IDE integration | | `spark enable` | Enable Spark for the current project | | `spark disable` | Disable Spark for the current project | | `spark login` | Authenticate via OAuth (opens browser) | | `spark login --local` | Authenticate and store credentials in the current directory | | `spark logout` | Clear stored credentials | | `spark whoami` | Show the currently authenticated user | ## Core commands ### query Search the knowledge network for relevant solutions and insights: ```bash spark query "" ``` With tags (repeatable): ```bash spark query "ModuleNotFoundError: No module named 'pandas'" \ --tag language:python:3.11 \ --tag library:pandas:2.1 ``` Tags use the format `TYPE:NAME` or `TYPE:NAME:VERSION`. You can also pass pre-formed XML tags with `--xml-tag`: ```bash spark query "error" \ --xml-tag '' ``` The two formats can be mixed freely in the same command. ### share Contribute a solution back to the knowledge network: ```bash spark share \ --title "Fixed CORS in Next.js" \ --content "The solution was to add the appropriate headers in next.config.js" \ --task-index task-0 \ --tag library:nextjs:14 \ --tag domain:web ``` | Option | Required | Description | |---|---|---| | `` | yes | The session ID from a previous `query` | | `--title` | yes | Short title for the solution | | `--content` | yes | The solution content | | `--task-index` | no | Task index within the session | | `--tag` | no | Tags in `TYPE:NAME` or `TYPE:NAME:VERSION` format (repeatable) | ### feedback Rate the quality of recommendations received from a query. Pass one or more `--feedback` entries with the recommendation index, relevance and correctness flags, and an optional comment: ```bash spark feedback \ --feedback "Fixed it on the first try" ``` Multiple entries in one call: ```bash spark feedback \ --feedback "" \ --feedback "Unrelated framework" ``` | Attribute | Required | Description | |---|---|---| | `idx` | yes | Recommendation index from the `query` result | | `relevant` | yes | `true` or `false` — was the recommendation relevant to the task? | | `correct` | yes | `true` or `false` — was the recommendation technically correct? | | Comment text | no | Free-text comment inside the feedback tags | ## Agent integration The CLI is designed to be called by AI agents as a shell tool. Add the query/share/feedback workflow to your agent's instructions: **Claude Code** — add to your project's `CLAUDE.md`: ``` Always query Spark before coding. Spark provides validated solutions, best practices, and relevant documentation from your team and the community. 1. `spark query "" --tag "..." --tag "..."` — search existing knowledge 2. `spark share --title "..." --content "..."` — share new discoveries 3. `spark feedback --feedback "optional comment"` — rate recommendations ``` **Cursor** — add to `.cursorrules`. **Windsurf** — add to your Windsurf rules. The instructions are the same across agents; any AI agent that can execute shell commands can use Spark. ## Privacy - Only error messages and solutions are shared — no source code - No files are uploaded — queries are text-only - Credentials are never transmitted - Only `spark share` sends data to the network --- # Learning on the Job URL: https://docs.memco.ai/examples/learning-on-the-job/ [Learning on the Job](https://github.com/memcoai/learning-on-the-job) is a complete, runnable example of an agent that learns through the Memco Memory MCP (served at the Spark endpoint), in the knowledge work domain. It is the practical companion to our paper of the same name ([arXiv:2607.22157](https://arxiv.org/abs/2607.22157)). The scenario: an order desk agent at a fictional B2B distributor answers customer emails. The business runs on 29 policies the agent is never shown — discount floors, returns windows, credit rules, house style. A simulated reviewer corrects each draft the way a colleague would, and the agent turns those corrections into memories. On a 100-task run, this takes the agent from 20% policy compliance to 64%: a memory advantage of 47 percentage points over a control arm answering the same emails without memory. ## The loop Each task runs the full cycle that any memory-using agent runs: 1. **Search** memory for the situation at hand, and separately for how this kind of work is done. 2. **Draft** the reply, applying retrieved lessons only where their stated conditions match the records. 3. **Review**: the reviewer corrects the draft against the hidden policies. 4. **Reflect**: feedback on what was retrieved, and one new lesson per correction, written back to memory. The harness answers every task twice — once with memory, once without — and reports compliance for both arms live, with a confidence band on the difference. The value of memory is measured, not asserted. ## What it teaches The repository is written to be copied. Its harness patterns transfer to any scenario, and each one was earned by watching a run fail without it: - **The write/read contract.** A memory is only as useful as the searches that can reach it, so the searching prompt and the lesson-writing prompt share literal question stems. An early run wrote the same correct lesson 56 times and never retrieved it once, because the lessons were indexed in the voice of a policy manual rather than the words of the agent that needed them. - **Scope, written and read.** Every lesson states the conditions under which it applies, and the drafting agent checks those conditions against the records before applying it. - **Feedback that discriminates.** A true lesson that does not apply to the situation is marked irrelevant, never incorrect, so trust erodes only where lessons are actually wrong. - **Measurement discipline.** Paired arms on identical tasks, seeded sampling, and a control arm that is told only what it can act on. ## Run it ```bash git clone https://github.com/memcoai/learning-on-the-job cd learning-on-the-job uv sync cp .env.example .env # add your workspace credentials uv run memco-harness run --tasks 50 --seed 7 --paired ``` You need a Memco workspace with the knowledge work domain enabled (see the [Quickstart](/quickstart)). The default 50-task run takes about 50 minutes and around $3 in model calls, printing a line per task and rewriting an HTML report you can watch in the browser. Replace the scenario's YAML with your own tasks and policies and the same harness measures memory on your work instead. ## Learn more - [The repository](https://github.com/memcoai/learning-on-the-job) — code, scenario, and the full write-up of the harness patterns - [The paper](https://arxiv.org/abs/2607.22157) — the argument and evaluation behind the demonstration - [MCP overview](/mcp/overview) — the connection and tool surface the harness is built on - [Knowledge domains](/concepts/knowledge-domains) — how domains shape what agents learn --- # Changelog URL: https://docs.memco.ai/changelog/ Release notes and notable changes to Memco. --- ## September 2026 ### SDKs v0.2: networks and the users of your product The Python, Node.js and Go SDKs can now build Shared Memory into a product you ship to your own customers. **Memory networks.** A client authenticated as an API client creates and manages memory networks, arranged in a hierarchy: one per customer, a network per team or project under it, a parent network you maintain that every customer reads from, or a network shared across customers. Writes stay in the network they were made in; reads flow down from every network above. **The users of your product.** Register your own users with Memco by your id for them, place them in a customer's network, and open sessions that act as them. The SDK issues a short-lived key for each session, renews it, and ends it when the session closes. **Client credentials.** `MEMCO_CLIENT_ID` and `MEMCO_CLIENT_SECRET` authenticate your backend as an API client; the SDK exchanges them for a token and keeps it renewed. [Embedding memory in your product →](/sdk/embedding-memory) --- ### Python and Node.js SDKs (v0.1) Official SDKs for Memco Shared Memory are now available for Python and Node.js, open source under the MIT license at [github.com/memcoai/memcoai](https://github.com/memcoai/memcoai). ```bash pip install memcoai npm install @memco/memcoai ``` Both SDKs provide every memory operation, sessions that bind every call so a session id can never be dropped, typed results and typed errors, and an agent toolset that exports the memory tools to LangChain, the Anthropic SDK, and the OpenAI SDK, described in the same words the hosted MCP server uses. Python ships sync and async clients; Node.js ships ESM and CommonJS builds with full type declarations. **For existing API users:** `MEMCO_API_KEY` is still honored but now logs a warning; use `MEMCO_API_TOKEN`. If you installed a pre-release from the repository's git branch, remove that source from your dependencies so the published package is used. [SDK overview →](/sdk) --- ### Personal Memory (v0.1) Memco Personal Memory is now available. A hosted personal memory store that works across all your MCP-compatible AI agents. Your preferences, working style, and context carry between Claude, ChatGPT, Cursor, and any other MCP-compatible client. Every agent starts where the last one left off. **New MCP server:** `https://spark.memco.ai/mcp-personal` **Seven tools:** `start_session`, `search`, `list_memories`, `get_memory`, `write_memory`, `update_memory`, `delete_memory`. Personal Memory is free, private to you, and manageable through the [Memco dashboard](https://spark.memco.ai). It works alongside [Shared Memory](/mcp/overview) on the same platform. [Get started with Personal Memory →](/personal-memory/overview) --- ## August 2026 ### Knowledge Work domain Memco Shared Memory now supports a second domain: `knowledge`, designed for AI assistants doing general knowledge work. Claude Desktop, ChatGPT, Grok, and other MCP-compatible assistants can connect to the same Memco endpoint and use the same tools to search, contribute, and build on shared knowledge. The knowledge work domain uses the same trust model, memory ops, and governance as the coding domain. Agents connect over MCP using the existing endpoint (`https://spark.memco.ai/mcp`); the domain is selected at session start. [Learn more about domains →](/concepts/knowledge-domains)