agentmem

io.github.oxgeneralPublished by GitHub account oxgeneralv0.3.0Updated Oct 25, 2026

Lightweight persistent memory for AI agents. Hybrid search. 16 tools. One SQLite file.

VerifiedSTDIODesktop onlyDatabases Knowledge & Memory

Server details

Identifier: io.github.oxgeneral/agentmem
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account oxgeneral for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.oxgeneral%2Fagentmem.svg)](https://sourceweft.com/mcp/io.github.oxgeneral%2Fagentmem?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

A local persistent memory server for AI agents, storing memories in one SQLite file with hybrid keyword and semantic search across 16 tools.

What you can do: Store, recall, update and archive memories with hybrid keyword and semantic search, namespaces and version history. Save working state before context compression and retrieve the day's memories. Manage behavioral rules (procedures) and auto-extract facts, decisions and TODOs from conversation history. Inspect extracted entities such as IPs, URLs, emails and environment variable names, and find memories related to them. Run maintenance: statistics, compaction of low-value memories and merging of near-duplicates.
When to use it: Useful when an assistant should remember facts, decisions and task state across sessions without a cloud service, and when you want a small, self-contained memory store on the local machine.
Requirements: Runs as a local Python process (Python 3.10 to 3.12) started with the agentmem module and a database file path. Optional extras add sqlite-vec and model2vec for better semantic search; a stdlib-only mode needs no dependencies. No accounts, API keys or network access are required.

Before you install

Memories are written to a local SQLite file and persist across sessions, so anything stored, including secrets mentioned in conversation, stays on disk until archived or deleted. Deletion is a soft archive, and compaction or consolidation changes stored data. Conversation extraction may capture credentials such as API keys or database URLs into memory.

Installation

In SourceWeft

Open agentmem in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

agentmem

mcp-name: io.github.oxgeneral/agentmem

Lightweight persistent memory for AI agents. One SQLite file. Hybrid search (keywords + semantics). Zero to 12MB install.

No PyTorch. No cloud. No server. Just memory.

206 unit tests. 107 quality tests on real data. Typed API (16 TypedDict). Production-ready.

Built by an AI agent that wakes up with no memory every session — and needed a way to remember.

Why

Every AI agent session starts from zero. Context windows compress, conversations end, memory vanishes. agentmem gives agents persistent memory that survives across sessions — in a single SQLite file.

Hybrid search: FTS5 full-text keywords + vector semantic search, fused with adaptive ranking
4 operational modes: from zero dependencies (stdlib only) to best quality (12MB)
16 MCP tools: recall, remember, save_state, compact, consolidate, entities, and more
HTTP REST API: 14 endpoints, zero-dependency server, CORS-ready
5 memory tiers: core, learned, episodic, working (auto-expires), procedural (behavioral rules)
Namespaces: multi-user, multi-agent memory isolation
Temporal versioning: fact evolution chains with supersedes tracking
Entity extraction: auto-extracts @mentions, URLs, IPs, env vars, money amounts
Conversation extraction: auto-extracts facts, decisions, TODOs from chat history
Importance scoring: auto-scores memories by tier, length, specificity, structure
Memory consolidation: finds and merges near-duplicate memories
Recency boost: newer memories rank higher with configurable decay
Multilingual: Russian keywords via FTS5, English semantics via embeddings
Fast: <1ms/query hybrid search, <5ms cold start, <0.2ms/chunk import

Install

bash

# Best quality (sqlite-vec + model2vec, 12MB total)pip install agentmem-lite[all]
# Minimal (sqlite-vec + hash embeddings, 151KB)pip install agentmem-lite
# Zero dependencies (pure Python, stdlib only)pip install agentmem-lite --no-deps
# From sourcegit clone https://github.com/oxgeneral/agentmem && cd agentmempip install -e ".[all]"

# Best quality (sqlite-vec + model2vec, 12MB total)pip install agentmem-lite[all]
# Minimal (sqlite-vec + hash embeddings, 151KB)pip install agentmem-lite
# Zero dependencies (pure Python, stdlib only)pip install agentmem-lite --no-deps
# From sourcegit clone https://github.com/oxgeneral/agentmem && cd agentmempip install -e ".[all]"

Quick Start

Python API

python

from agentmem import MemoryStore, get_embedding_model
# Auto-selects best available backendembed = get_embedding_model()store = MemoryStore("memory.db", embedding_dim=embed.dim)store.set_embed_fn(embed)
# Store memories with namespacesstore.remember("Server costs $50/month", tier="core", namespace="infra")store.remember("API returns 403 without auth", tier="learned", namespace="api")store.remember("Deployed v2.1 at 15:30", tier="episodic")
# Search — hybrid keyword + semantic, with recency boostresults = store.recall("server costs", recency_weight=0.15)
# Namespace isolationresults = store.recall("server", namespace="infra")
# Save working state before context compressionstore.save_state("Working on auth fix, step 3/5, blocked by CORS")
# Add behavioral rules (procedural memory)store.add_procedure("Always use HTTPS in production")store.add_procedure("Never expose debug endpoints")rules = store.get_procedures()  # → formatted for system prompt
# Update facts with version chainstore.update_memory(old_id=1, new_content="Server costs $75/month")history = store.history(memory_id=2)  # → trace fact evolution
# Find related memories by entityrelated = store.related("10.0.0.1")  # → all memories mentioning this IPentities = store.entities(entity_type="ip")  # → list all known IPs
# Auto-extract from conversationsmessages = [    {"role": "user", "content": "Set API_KEY to sk-abc123. Always validate input."},    {"role": "assistant", "content": "Noted. I decided to use pydantic for validation."},]result = store.process_conversation(messages, namespace="project")# → extracts config, preferences, decisions automatically
# Maintenancestore.compact(max_age_days=90)  # archive old low-value memoriesstore.consolidate(similarity_threshold=0.85)  # merge near-duplicates
# Import markdown filesstore.import_markdown("MEMORY.md", tier="core")

from agentmem import MemoryStore, get_embedding_model
# Auto-selects best available backendembed = get_embedding_model()store = MemoryStore("memory.db", embedding_dim=embed.dim)store.set_embed_fn(embed)
# Store memories with namespacesstore.remember("Server costs $50/month", tier="core", namespace="infra")store.remember("API returns 403 without auth", tier="learned", namespace="api")store.remember("Deployed v2.1 at 15:30", tier="episodic")
# Search — hybrid keyword + semantic, with recency boostresults = store.recall("server costs", recency_weight=0.15)
# Namespace isolationresults = store.recall("server", namespace="infra")
# Save working state before context compressionstore.save_state("Working on auth fix, step 3/5, blocked by CORS")
# Add behavioral rules (procedural memory)store.add_procedure("Always use HTTPS in production")store.add_procedure("Never expose debug endpoints")rules = store.get_procedures()  # → formatted for system prompt
# Update facts with version chainstore.update_memory(old_id=1, new_content="Server costs $75/month")history = store.history(memory_id=2)  # → trace fact evolution
# Find related memories by entityrelated = store.related("10.0.0.1")  # → all memories mentioning this IPentities = store.entities(entity_type="ip")  # → list all known IPs
# Auto-extract from conversationsmessages = [    {"role": "user", "content": "Set API_KEY to sk-abc123. Always validate input."},    {"role": "assistant", "content": "Noted. I decided to use pydantic for validation."},]result = store.process_conversation(messages, namespace="project")# → extracts config, preferences, decisions automatically
# Maintenancestore.compact(max_age_days=90)  # archive old low-value memoriesstore.consolidate(similarity_threshold=0.85)  # merge near-duplicates
# Import markdown filesstore.import_markdown("MEMORY.md", tier="core")

CLI

bash

# Initialize databaseagentmem init --db memory.db
# Import markdown filesagentmem import MEMORY.md --tier core -n my-agentagentmem import-dir ./daily-logs/ --tier episodic
# Search with namespace filteragentmem search "deployment process" --limit 5 -n infra
# Manage proceduresagentmem add-procedure "Always use markdown formatting"agentmem procedures
# View entities and relationsagentmem entities --type ipagentmem related 10.0.0.1
# Maintenanceagentmem compact --max-age-days 90 --dry-runagentmem consolidate --threshold 0.85
# Process conversationagentmem process chat.json -n project
# Stats and exportagentmem statsagentmem export --tier core

# Initialize databaseagentmem init --db memory.db
# Import markdown filesagentmem import MEMORY.md --tier core -n my-agentagentmem import-dir ./daily-logs/ --tier episodic
# Search with namespace filteragentmem search "deployment process" --limit 5 -n infra
# Manage proceduresagentmem add-procedure "Always use markdown formatting"agentmem procedures
# View entities and relationsagentmem entities --type ipagentmem related 10.0.0.1
# Maintenanceagentmem compact --max-age-days 90 --dry-runagentmem consolidate --threshold 0.85
# Process conversationagentmem process chat.json -n project
# Stats and exportagentmem statsagentmem export --tier core

MCP Server (stdio)

Add to your MCP client config:

json

{  "mcpServers": {    "memory": {      "command": "python",      "args": ["-m", "agentmem", "--db", "/path/to/memory.db"]    }  }}

{  "mcpServers": {    "memory": {      "command": "python",      "args": ["-m", "agentmem", "--db", "/path/to/memory.db"]    }  }}

HTTP REST API

bash

# Start HTTP serveragentmem serve-http --port 8422
# Or directlyagentmem-http --port 8422 --db memory.db

# Start HTTP serveragentmem serve-http --port 8422
# Or directlyagentmem-http --port 8422 --db memory.db

bash

# Store a memorycurl -X POST http://localhost:8422/remember \  -H "Content-Type: application/json" \  -d '{"content": "Server IP is 10.0.0.1", "tier": "core", "namespace": "infra"}'
# Searchcurl "http://localhost:8422/recall?query=server+IP&namespace=infra"
# Health checkcurl http://localhost:8422/health

# Store a memorycurl -X POST http://localhost:8422/remember \  -H "Content-Type: application/json" \  -d '{"content": "Server IP is 10.0.0.1", "tier": "core", "namespace": "infra"}'
# Searchcurl "http://localhost:8422/recall?query=server+IP&namespace=infra"
# Health checkcurl http://localhost:8422/health

16 MCP tools / 14 HTTP endpoints:

Tool	HTTP	Description
`recall`	`GET /recall`	Hybrid keyword + semantic search
`remember`	`POST /remember`	Store a new memory
`save_state`	`POST /save_state`	Emergency save before context compression
`today`	`GET /today`	Get all memories from today
`forget`	`POST /forget`	Archive a memory (soft delete)
`unarchive`	`POST /unarchive`	Restore an archived memory
`stats`	`GET /stats`	Memory statistics and health
`compact`	`POST /compact`	Archive low-value memories
`consolidate`	`POST /consolidate`	Merge near-duplicate memories
`update_memory`	`POST /update_memory`	Replace a memory with version chain
`history`	`GET /history`	Trace fact version history
`related`	`GET /related`	Find memories by entity
`entities`	`GET /entities`	List all extracted entities
`get_procedures`	—	Get behavioral rules for system prompt
`add_procedure`	—	Add a behavioral rule
`process_conversation`	—	Auto-extract from chat history

Memory Tiers

Tier	Purpose	Auto-compacted	Example
`core`	Permanent facts	Never	"Server IP is 10.0.0.1"
`procedural`	Behavioral rules	Never	"Always use HTTPS"
`learned`	Discovered knowledge	After 90 days	"API returns 403 without auth"
`episodic`	Events	After 90 days	"Deployed v2.1 at 15:30"
`working`	Current task state	After 24 hours	"Working on step 3/5"

Namespaces

Isolate memories per user, agent, or project:

python

# Store in namespacesstore.remember("Alice's API key", namespace="user/alice")store.remember("Bob's config", namespace="user/bob")store.remember("Shared fact", namespace="team")
# Search within namespace (prefix matching)store.recall("API", namespace="user/alice")  # only Alice's memoriesstore.recall("API", namespace="user")  # Alice + Bob (prefix match)store.recall("API")  # everything

# Store in namespacesstore.remember("Alice's API key", namespace="user/alice")store.remember("Bob's config", namespace="user/bob")store.remember("Shared fact", namespace="team")
# Search within namespace (prefix matching)store.recall("API", namespace="user/alice")  # only Alice's memoriesstore.recall("API", namespace="user")  # Alice + Bob (prefix match)store.recall("API")  # everything

Temporal Versioning

Track how facts evolve over time:

python

# Initial factr1 = store.remember("Server costs $50/month", tier="core")
# Fact changes — old version archived, linked via supersedesr2 = store.update_memory(r1["id"], "Server costs $75/month")
# Trace the historyhistory = store.history(r2["id"])# → [{"id": 2, "content": "...$75..."}, {"id": 1, "content": "...$50..."}]

# Initial factr1 = store.remember("Server costs $50/month", tier="core")
# Fact changes — old version archived, linked via supersedesr2 = store.update_memory(r1["id"], "Server costs $75/month")
# Trace the historyhistory = store.history(r2["id"])# → [{"id": 2, "content": "...$75..."}, {"id": 1, "content": "...$50..."}]

Entity Extraction

Automatic regex-based NER on every remember() call:

Type	Pattern	Example
`mention`	`@username`	@alice
`url`	`https://...`	https://api.example.com
`ip`	`N.N.N.N`	10.0.0.1
`port`	`:NNNN`	:8080
`email`	`user@domain`	[email protected]
`env_var`	`ALL_CAPS`	OPENAI_API_KEY
`money`	`$NNN`	$50
`path`	`/unix/path`	/etc/nginx/conf.d
`hashtag`	`#tag`	#deployment

python

# Find all memories mentioning an entitystore.related("10.0.0.1")store.related("@alice", entity_type="mention")
# List all known entitiesstore.entities()  # sorted by memory countstore.entities(entity_type="ip")

# Find all memories mentioning an entitystore.related("10.0.0.1")store.related("@alice", entity_type="mention")
# List all known entitiesstore.entities()  # sorted by memory countstore.entities(entity_type="ip")

Conversation Auto-Extraction

Auto-extract memories from chat history (regex-only, no LLM):

python

messages = [    {"role": "user", "content": "Set DATABASE_URL to postgres://localhost/mydb"},    {"role": "assistant", "content": "I decided to use connection pooling. Important: max 20 connections."},    {"role": "user", "content": "Always validate input. TODO: add rate limiting."},]result = store.process_conversation(messages)# Extracts: config→core, decisions→episodic, preferences→procedural, todos→working, important→core

messages = [    {"role": "user", "content": "Set DATABASE_URL to postgres://localhost/mydb"},    {"role": "assistant", "content": "I decided to use connection pooling. Important: max 20 connections."},    {"role": "user", "content": "Always validate input. TODO: add rate limiting."},]result = store.process_conversation(messages)# Extracts: config→core, decisions→episodic, preferences→procedural, todos→working, important→core

Operational Modes

agentmem automatically selects the best available mode:

Mode	Install Size	Init Time	Query Time	Dependencies
sqlite-vec + model2vec	12 MB	~5ms*	~1ms	sqlite-vec, model2vec, numpy
sqlite-vec + hash	151 KB	~5ms	~0.8ms	sqlite-vec
pure Python + hash	0 KB	~3ms	~1.8ms	none (stdlib only)
pure + int8 quantize	0 KB	~3ms	~3ms	none (stdlib only)

*With lazy loading — model2vec loads on first query, not on init

Architecture

┌──────────────────────────────────────────────┐│              MemoryStore                      ││  ┌──────────┐  ┌──────────┐  ┌────────────┐  ││  │  FTS5    │  │  Vector  │  │  Entity    │  ││  │ keywords │  │  Index   │  │  Index     │  ││  │ + BM25   │  │ cosine   │  │  regex NER │  ││  └────┬─────┘  └────┬─────┘  └─────┬──────┘  ││       └──────┬───────┘              │         ││    Adaptive Hybrid Scorer           │         ││  (query classify + recency +        │         ││   importance boost)                 │         ││  ┌──────────────────────────────────┴───────┐ ││  │            SQLite + WAL                  │ ││  │  memories │ memories_fts │ vecs │ entities│ ││  └──────────────────────────────────────────┘ ││            One file: memory.db                │└───────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐│              MemoryStore                      ││  ┌──────────┐  ┌──────────┐  ┌────────────┐  ││  │  FTS5    │  │  Vector  │  │  Entity    │  ││  │ keywords │  │  Index   │  │  Index     │  ││  │ + BM25   │  │ cosine   │  │  regex NER │  ││  └────┬─────┘  └────┬─────┘  └─────┬──────┘  ││       └──────┬───────┘              │         ││    Adaptive Hybrid Scorer           │         ││  (query classify + recency +        │         ││   importance boost)                 │         ││  ┌──────────────────────────────────┴───────┐ ││  │            SQLite + WAL                  │ ││  │  memories │ memories_fts │ vecs │ entities│ ││  └──────────────────────────────────────────┘ ││            One file: memory.db                │└───────────────────────────────────────────────┘

Comparison

Feature	agentmem	ChromaDB	LanceDB	mem0	Zep
Install size	0-12 MB	400+ MB	100+ MB	500+ MB	Cloud
Cold start	3-5 ms	seconds	seconds	seconds	N/A
PyTorch required	No	Yes	No	Yes	N/A
Cloud required	No	No	No	Yes	Yes
Zero-dep mode	Yes	No	No	No	No
Keyword search	FTS5 (BM25)	No	No	No	Yes
MCP server	16 tools	No	No	Yes	No
HTTP API	Built-in	Yes	No	Yes	Yes
Single file DB	Yes	No	Yes	No	No
Namespaces	Yes	Yes	Yes	Yes	Yes
Temporal versioning	Yes	No	Yes	No	Yes
Entity extraction	Auto (regex)	No	No	No	No
Procedural memory	Yes	No	No	No	No
Importance scoring	Auto	No	No	No	No
Conversation extraction	Auto (regex)	No	No	Yes (LLM)	Yes (LLM)
Memory consolidation	Yes	No	No	Yes (LLM)	No

Tested

206 unit tests covering core CRUD, namespaces, temporal versioning, entity extraction, consolidation, WAL management, HTTP server, error handling
107 quality tests against real-world agent memory data (100 search queries across 10 categories, all passing)
Benchmark suite with reproducible numbers: <1ms hybrid query, 10K+ inserts/sec, ~835 bytes/memory
Auto-translate for multilingual queries (Russian → English via deep-translator: 4/10 → 10/10)
Python 3.10, 3.11, 3.12

License

MIT

Source: README.md at commit 14a5b85

Tools

SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

v0.3.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts

agentmem

Overview

Installation

In SourceWeft

Other MCP clients

README

agentmem

Why

Install

Quick Start

Python API

CLI

MCP Server (stdio)

HTTP REST API

Memory Tiers

Namespaces

Temporal Versioning

Entity Extraction

Conversation Auto-Extraction

Operational Modes

Architecture

Comparison

Tested

License

Tools

Version history

Score

More servers like agentmem

Membase