TinyMem is one local stdio MCP server (shared SQLite file, no embeddings) that stores and retrieves durable project memory for coding agents.
add_memory — store a durable fact, preference, decision, or plan (1–2 sentences), with optional kind, valid_until expiry, and namespace.
search_memories — offline lexical (FTS5/BM25 + recency) search of active memories; filter by kind, cap limit at 20.
update_memory — correct an existing memory by id instead of re-adding it; bumps updated_at so fresher facts rank higher; valid_until: null clears expiry.
get_profile / set_profile — read or write the small static per-namespace profile (stack, conventions, commands); empty profile clears it.
memory_stats — counts by namespace/kind plus database size.
delete_memory — hide a memory from search (id only); explicitly not secure erasure.
Scope rules: omitting namespace uses the session namespace; passing it explicitly is the only cross-project read; update_memory and delete_memory reject ids outside the session namespace.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TinyMem remember we use pnpm instead of npm for this project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Local memory with one MCP server for every coding agent.
One Python stdio MCP server. Pi, Cursor, Claude Code, VS Code, and Codex launch that same process and share one SQLite file.
0.1.0-beta.1 was a different product (Rust, Pi-only). It was never
published. Do not use that tag. The first beta of this product is
0.2.0-beta.1, distributed as a pinned source tag (not PyPI or release assets).
Qualified beta: macOS arm64, Python 3.14.7, Pi 1.0.0. Cursor, Claude Code,
VS Code, and Codex configs are generated but not live-qualified.
See docs/BETA_CHECKS.md for the recorded checks and limitations.
Requires Python 3.14 or newer. No third-party runtime dependencies.
git clone --branch 0.2.0-beta.1 --single-branch https://github.com/vikirams/tinymem
cd tinymem
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .This provides the tinymem console script. Keep this venv's bin directory
on PATH when launching your agents; connect records tinymem mcp, not
an absolute interpreter path. For development, clone main instead of the
beta tag.
Related MCP server: LumenCore
In the project directory, register the same server with every agent:
tinymem connect
tinymem connect --hooks --disciplineconnect always writes MCP config: tinymem mcp plus TINYMEM_DB and
TINYMEM_NAMESPACE into .pi/mcp.json, .cursor/mcp.json, .mcp.json,
.vscode/mcp.json, and .codex/config.toml.
--hooks is optional. On Claude Code and Cursor it registers a SessionStart
Hook that runs tinymem context (Profile plus a recency Index of five
Memories). Hook commands pin the same database and project namespace as MCP,
independently of the host environment. Re-run tinymem connect --hooks to
replace older hook commands; unrelated hooks are preserved.
The Hook must not persist. If it fails, the session still starts.
Pi, VS Code, and Codex stay MCP-only unless you add --discipline.
--discipline copies the TinyMem skill (skills/tinymem/SKILL.md) and, if
the project has no AGENTS.md, writes a compact copy. Cursor also gets
.cursor/rules/tinymem.mdc.
The namespace defaults to the git toplevel directory name, sanitized to
[A-Za-z0-9_:-]{1,64}. Select agents with --agent pi --agent cursor.
Config output alone is not qualification; see docs/BETA_CHECKS.md.
Seven tools, same for every agent:
add_memory — store a durable fact, preference, decision, or plan.
search_memories — search active memories.
update_memory — correct a memory instead of re-adding.
get_profile — get the static profile for a namespace.
set_profile — set the static profile for a namespace.
memory_stats — counts by namespace/kind plus database size.
delete_memory — hide a memory from search.
Other commands:
tinymem mcp # serve the stdio MCP server
tinymem connect [--hooks] [--discipline]
tinymem context [--format text|claude|cursor]
tinymem stats [--json] # counts and database size
tinymem purge [--grace-days N] # hard-delete hidden/expired rows, then vacuum
tinymem profile get [--namespace N]
tinymem profile set [--namespace N] "text" | --clearadd_memory only for durable facts, preferences, decisions, plans in
1-2 sentences (aim under 500 chars). Never re-add a correction; use
update_memory, which bumps updated_at so fresher facts rank higher.
Set valid_until (YYYY-MM-DD) for transient facts like exams,
branches, or work in progress. set_profile for stack, conventions, commands, and a short code map.
Refuse transcripts, tool logs, file bodies, and same-day recaps.
Prefer get_profile first, then search_memories with 1-3 distinctive
terms and limit 3-5; shorten the query on zero hits. Omitting
namespace searches the session namespace (TINYMEM_NAMESPACE).
Passing namespace explicitly is the only cross-project read.
update_memory and delete_memory refuse ids outside the session
namespace.
The database is a plain SQLite file, default ~/.tinymem/tinymem.db
(TINYMEM_DB overrides it). Anyone with file access can read every
namespace. Namespace is a label, not auth and not encryption.
delete_memory hides a note from search (deleted_at plus FTS removal
in one transaction). The row stays in the file. purge hard-deletes
hidden or long-expired rows and runs VACUUM when SQLite allows it.
Neither is secure erasure: free pages, WAL, and file copies may retain
content.
Offline lexical search: FTS5 with porter stemming, prefix match, and
BM25 plus recency. Model-free and offline. Lexical search is not
semantic search. An optional SessionStart Hook may inject Profile plus a
recency Index; full Memory text stays behind search_memories. There is
no embedding, repository index, capture of tool output, or required proxy.
Beta makes no claim that memory improves coding results.
Rust engine, native archives, Pi extension, Cloudflare gateway,
Python/TypeScript SDKs, team auth, encryption, secure deletion,
export/import, Windows, Intel macOS, Linux qualification beyond the
cells recorded in docs/BETA_CHECKS.md, and publishing to PyPI or
GitHub Releases.
python3 -m unittest discover -s tests -vSee CONTRIBUTING.md, SECURITY.md, CHANGELOG.md, docs/BETA.md.
License: MIT (LICENSE).
Store a durable fact, preference, decision, or plan in 1-2 sentences. Never re-add a correction; use update_memory. Set valid_until for transient facts.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | fact | |
| content | Yes | ||
| namespace | No | ||
| valid_until | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the write/no-overwrite profile is partly given. The description adds real value by warning that corrections must not be re-added (consistent with idempotentHint=false) and by scoping storage to short, durable text with valid_until for transient content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short imperative sentences with zero filler, and the routing constraint is front-loaded after the core purpose. Every clause carries usable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter write tool with no output schema but full annotation coverage, the description covers purpose, the main routing hazard, and one parameter. The gaps are namespace semantics and any hint of what is returned after storing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry the load. It partially does: it names the four valid kinds (matching the enum), implies the content format ('1-2 sentences'), and explains valid_until's purpose, but never mentions the namespace parameter or its naming pattern.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (store) plus resource (durable fact/preference/decision/plan), with the accepted content kinds enumerated. It explicitly distinguishes itself from the sibling update_memory, so an agent can tell the two apart without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Contains all three elements: when to use (durable facts, preferences, decisions, plans), when not to (never re-add a correction), and the named alternative (update_memory). It also adds a conditional routing rule for transient facts via valid_until.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hide a memory from search. This is not secure erasure of the database file.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, but the description adds genuinely useful context beyond them: the effect is a search-level hide, not secure erasure of the underlying file. Missing is whether the operation is reversible or requires specific permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler; the most important semantic caveat follows immediately after the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive single-parameter mutation with no output schema, the description supplies the crucial 'not real erasure' caveat but omits the meaning of the id, recoverability of the hidden memory, and any permission requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single 'id' parameter has no description in the schema, so the description bears the burden of clarifying it — yet it never mentions the identifier at all. No meaning is added beyond the raw type and length constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Hide a memory from search') and accurately characterizes the operation as a soft hide rather than true deletion. It distinguishes the tool's effect from what its name ('delete') would imply, though it does not contrast it against siblings like update_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says nothing about when to use this tool versus alternatives such as update_memory or add_memory, nor about prerequisites or conditions. The usage context is only loosely implied by 'hide from search'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the small static profile for a namespace (stack, conventions, commands). Cheaper than search; read this first.
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine context beyond that: the payload is 'small' and 'static', and the operation is cheaper than a search, which tells the agent about cost and caching behavior. It does not describe auth requirements or the default namespace when omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence that front-loads the resource and its contents, then adds the routing cue. Nothing is wasted and the ordering advice is placed where it is most useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, no-output-schema tool, the description tells the agent what comes back (stack, conventions, commands) and when to prefer it over search. The only real gap is behavior when the optional namespace argument is omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the schema only carries a regex pattern and length bounds. The description ties the call to 'a namespace' but does not explain the parameter's semantics — notably that it is optional, what namespace is assumed when omitted, or what valid namespace values mean. Minimal compensation for a low-coverage schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get the small static profile for a namespace') and enumerates what it returns (stack, conventions, commands). It also distinguishes itself from siblings by naming search as the more expensive alternative, so an agent can tell it apart from search_memories without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Cheaper than search; read this first' gives clear and actionable ordering guidance relative to search_memories. It stops short of stating explicit exclusions (e.g., when profile data is stale, or when set_profile/update_memory should be used instead), so it is not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show memory counts by namespace/kind plus database size. Use to check quota before bulk adds.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful context by disclosing the returned content (per-namespace/kind counts plus DB size) and implying it is a cheap, safe pre-flight call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero waste, with the content of the report front-loaded before the usage hint. Nothing could be trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing the return value and does so reasonably (counts by namespace/kind, database size). It stops short of mentioning output format or units, but for a no-argument read tool this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing to document; the schema is empty and 100% covered. Baseline 4 applies, and the description correctly does not invent parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb+resource (memory_stats) and enumerates exactly what it reports: counts by namespace/kind plus database size. This is clearly distinct from the sibling mutation/search/profile tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use to check quota before bulk adds" gives an explicit, actionable when-to-use tied to the add_memory sibling. It doesn't name an alternative, but no sibling reports stats, so there is little to disambiguate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search active memories. Use 1-3 distinctive terms with limit 3-5; shorten the query on zero hits. Prefer get_profile for stack/conventions.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| limit | No | ||
| query | Yes | ||
| namespace | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds the useful behavioral detail that only "active" memories are searched and how to recover from zero hits, but says nothing about result ordering or match semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the action, then technique, then alternative. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema and full annotation coverage, the description is serviceable, but with 0% schema coverage the undocumented kind and namespace parameters leave the callable surface incompletely explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 4 parameters, so the description carries the full burden. It gives guidance for query and limit, but the kind enum (fact/preference/decision/plan) and the namespace pattern parameter are left entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ("Search active memories") and scopes it to active rather than archived records. It does not explicitly contrast with the many write siblings (add/update/delete_memory), but the read intent is unambiguous from the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete operational guidance (1-3 distinctive terms, limit 3-5, shorten query on zero hits) and names an alternative with its condition: "Prefer get_profile for stack/conventions." It stops short of covering when to use memory_stats or the write siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the static profile for a namespace (aim under 4000 chars). Pass an empty profile to clear it.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | Yes | ||
| namespace | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the write/idempotent nature is covered. The description adds two useful behavioral facts beyond the annotations: the ~4000-char size guidance and that an empty value clears the profile. It does not say what happens to an existing profile on overwrite or whether any authorization is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the primary action and immediately followed by the size and clearing semantics. No filler or restated name/title content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and only two parameters, so the description should be near-sufficient, but it omits the namespace parameter entirely and gives no return/effect information. The clearing and size behaviors are covered, leaving a moderate gap for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden, and it only partially does: it explains the size expectation for `profile` (matching maxLength 4000) and its empty-string semantics. The `namespace` parameter is never mentioned — no default, no explanation of the allowed pattern, and no statement of which namespace applies if omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource: 'Set the static profile for a namespace,' and the word 'static' helps distinguish this durable profile from the memory siblings. It stops short of naming get_profile as the read counterpart or clarifying how the profile relates to the add_memory/search_memories family.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives one concrete usage instruction — pass an empty profile to clear it — which implies the clearing use case, but there is no guidance on when to set a profile versus store memories, nor any reference to get_profile for reading. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Correct a memory instead of re-adding. Bumps updated_at so fresher facts rank higher. Pass valid_until null to clear expiry.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| kind | No | ||
| content | No | ||
| valid_until | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover idempotency and non-destructiveness, but the description adds value beyond them: it discloses the updated_at side effect (ranking implication) and the valid_until=null clearing behavior. These are real behavioral traits not derivable from the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, purpose front-loaded, each adding a distinct fact (routing, ranking effect, param behavior). No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 4-param update tool with no output schema, the description covers purpose, usage routing, side effects, and the trickiest parameter. Only kind's enum domain and partial-update semantics are unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning. It usefully explains valid_until's null semantics but leaves id, kind's enum values, and content's role undocumented. Partial compensation justifies a mid score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Correct a memory") and explicitly frames it as the alternative to re-adding, which separates it from the add_memory sibling. It's clear, though "correct" is slightly softer than a crisp "update existing memory fields".
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "instead of re-adding" gives a clear when-to-use signal that routes the agent away from add_memory. No explicit when-not or edge conditions, but the core selection decision is covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0-devadd_memorydelete_memoryget_profilememory_statssearch_memoriesset_profileupdate_memoryScored across 7 tools
Each tool has a clearly distinct purpose: add/update/delete/search memories operate on individual facts while get_profile/set_profile manage static namespace data and memory_stats reports counts. The descriptions even cross-reference each other (e.g., 'use update_memory' vs re-adding), leaving little room for misselection.
Six of seven tools follow a consistent snake_case verb_noun pattern (add_memory, search_memories, update_memory, get_profile, set_profile, delete_memory). Only memory_stats deviates as a noun-only label, a minor inconsistency that is still readable.
Seven tools is well-scoped for a memory store, covering the essential lifecycle operations without redundant or filler tools. Each tool clearly earns its place.
The surface covers full lifecycle CRUD (add/search/update/delete) plus profile get/set and stats, which is strong. Minor gaps exist, such as no list-all/export or namespace management, but core agent workflows are fully supported.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Hosted agent memory: store, search, and recall facts across sessions from any MCP client.
Persistent cloud memory for AI agents. Store and search key-value memories across sessions.
