> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Coding agent with project memory

Repository scoped sessions and MCP.

This guide shows how to build a coding assistant - similar to an in-editor AI agent - that uses SurrealDB Agent Memory via MCP to remember coding conventions, past decisions, team preferences, and ongoing work across sessions.

## What the agent remembers

A coding agent working on a repository accumulates a surprising amount of context that is useful across sessions:

- **Coding conventions**: "We use `Result<T, Error>` not exceptions in this codebase"
- **Past decisions**: "We chose Tanstack Query over SWR because of the devtools"
- **Team preferences**: "Alice prefers functional components; Bob owns the auth module"
- **Ongoing work**: "The migration to the analytics database is 80% complete, blocked on the auth service"
- **Documentation**: Product specs, architecture decisions, API contracts

Without persistent memory, every new session starts from scratch. With SurrealDB Agent Memory, the agent can recall relevant context at the start of each conversation and update its memory as new decisions are made.

---

## Installing the MCP server

SurrealDB Agent Memory serves MCP at `/mcp` on your context host, shown in the SurrealDB Studio **API keys** view. Install it into your editor with [`install-mcp`](https://github.com/supermemoryai/install-mcp) - the `/mcp` URL is the first argument, auth goes through `--header`, and `--oauth no` skips the OAuth prompt:

```bash
# Install for Cursor
npx install-mcp https://<your-context-host>/mcp \
    --client cursor \
    --header "Authorization: Bearer <your-api-key>" \
    --oauth no
```

This registers the SurrealDB Agent Memory MCP server in your editor's MCP configuration. Memory is scoped per tool call with a `scope` argument (for example `["org/acme/project/my-repo"]`), not at install time.

### Manual configuration

If you prefer to configure the MCP server manually, add it to your editor's MCP config:

```json
{
  "mcpServers": {
    "agent-memory": {
      "url": "https://<your-context-host>/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

---

## Scope per repository

Scoping memory to a repository ensures that conventions from one project do not bleed into another. Use the `project` dimension in the scope:

```json
["org/acme/project/my-repo"]
```

With this scope, all memory stored during sessions for `my-repo` is isolated from memory for other projects. No read reaches an ancestor scope, so team-wide knowledge (e.g. company-wide conventions) stored at the `org` scope is not visible through a project lens. To share it, either store it with an OR scope such as `["org/acme/project/my-repo", "org/acme/project/other-repo"]`, or read it with a second lens on the `org` path, using a key whose grants cover that path.

---

## Session start: loading context

At the beginning of each coding session, the agent should call `context` to load relevant context before it responds to the first user message:

```text
Tool: context
Arguments: {
  "query": "project conventions and active work for my-repo",
  "lens": ["org/acme/project/my-repo"]
}
```

This returns a markdown context block of what SurrealDB Agent Memory knows about this project: ongoing work, decisions, preferences, and conventions. The agent includes this in its system context before the user's first message.

---

## Storing decisions

When a significant decision is made during a session, use `remember` to persist it:

```text
Tool: remember
Arguments: {
  "text": "We decided to use Zod for runtime validation because it integrates with our existing TypeScript types and provides better error messages than Yup.",
  "scope": ["org/acme/project/my-repo"]
}
```

For team preferences and conventions, the agent can store these automatically when it identifies a standing directive in the conversation:

```text
User: \
  "Always use named exports in this project, never default exports."

Tool: remember
Arguments: {
  "text": "Always use named exports, never default exports.",
  "scope": ["org/acme/project/my-repo"]
}
```

---

## Documentation lookup with recall

When the user asks a question that might be answered by project documentation you have uploaded, use `recall`:

```text
Tool: recall
Arguments: {
  "query": "What is the authentication flow for the API?",
  "lens": ["org/acme/project/my-repo"],
  "k": 3
}
```

This searches memory, including relevant passages from uploaded documents (architecture decision records, API specs, README files).

To upload project documentation:

```bash
# One document at a time
agent-memory documents upload ./docs/architecture.md --label "topic=architecture"
agent-memory documents upload ./docs/api-spec.yaml --label "topic=api"

# Or ingest a whole folder recursively
agent-memory ingest ./docs --label "topic=project-docs"
```

---

## Full session flow

Here is what a typical coding session looks like with SurrealDB Agent Memory MCP integrated:

**Session start**

```text
Tool: context
→ Returns: ongoing work, conventions, decisions, preferences

Tool: recall (query = user's first message)
→ Returns: relevant documentation passages
```

**During the session**

```text
User: "How should I handle errors in the new payment module?"

Tool: recall
Arguments: { "query": "error handling patterns", "lens": ["org/acme/project/my-repo"] }
→ Returns: "Use Result<T, Error> not exceptions in this codebase"

Agent: "Based on this project's conventions, you should use Result<T, Error>…"
```

**When a decision is made**

```text
User: "Let's use Stripe's webhook library directly rather than wrapping it."

Tool: remember
Arguments: {
  "text": "Payment module uses Stripe webhook library directly, no wrapper.",
  "scope": ["org/acme/project/my-repo"]
}
```

**Session end (optional)**

```text
Tool: reflect
Arguments: {
  "query": "What was decided and what needs follow-up?",
  "persist": true
}
→ Returns a reflection, and stores the attributes it derives
```

---

## Multi-developer teams

When multiple developers work on the same project, they share memory at the project scope. Each developer's session contributes to and reads from the same experiential memory.

For individual preferences, use the `user` dimension alongside `project`:

```json
["org/acme/project/my-repo/user/alice"]
```

Alice's personal preferences (code style, preferred approaches) live at the user scope. Project-wide conventions live at the project scope. A key whose grants cover `org/acme/project/my-repo/*` reads both. A read limited to Alice's path returns only her preferences, because no read reaches an ancestor scope.