Memco
SDK

Embedding Memory in Your Product

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

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

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 and Node.js 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:

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")
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 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.

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

Edit this page on GitHub

Building an Agent

How to give an agent you build yourself a shared memory: the learning loop, the toolset export for LangChain, Anthropic and OpenAI, and the patterns that make it work.

Overview

Next Page

On this page

Embedding Memory in Your ProductWho is whoMemory networksManaging networks and usersPythonNode.jsActing for the users of your productThe learning loop, at the product levelSeeding a networkData residency and isolationNext steps