Taos本地AI记忆系统

Dependencies & Acknowledgements

Core taOSmd (the 97.0% benchmark) is fully self-contained, it uses only standard packages (SQLite, numpy, ONNX Runtime) plus the MiniLM embedding model. No external servers or forked repos needed.

Optional integrations for the full taOS stack:

Getting Started

Let your agent install it

The cleanest way to install taOSmd is to ask your agent to do it. Paste this message into Claude Code, Cursor, your OpenClaw shell, whatever:

Please install taOSmd as my memory system. The repo is github.com/jaylfc/taosmd. 1. Read the README so you understand what you're installing. 2. Run the install script: curl -fsSL https://raw.githubusercontent.com/jaylfc/taosmd/master/scripts/setup.sh | bash. Report any errors and stop if it fails. 3. Register yourself as an agent so you have your own isolated index. Pick a stable agent name (lowercase, no spaces), the same name you'll use every time you call the librarian. If I have multiple agents in this framework, ask me what to name this one before registering. 4. Verify the install: call taosmd.search("hello", agent="<your-name>"), it should return an empty result, not an error. 5. Append the "Memory, taOSmd" rules block to my agent file (CLAUDE.md / system prompt / AGENTS.md, whatever your framework reads every turn). Pull the block via python -c "import taosmd; print(taosmd.agent_rules())", the file is shipped as package data at taosmd/docs/agent-rules.md so this works from both editable and wheel installs. Replace <your-agent-name> with the name you registered as. 6. Confirm it's installed and tell me your agent name so I know how to refer to your memory. Don't summarise the repo or paraphrase the rules. Copy them verbatim, the wording is the contract.

The agent will pull the repo, run the install, register itself, append the per-turn rules block to its own instruction file, and verify everything works. After that, every turn it runs it'll check the librarian when it's uncertain, see taOSmd/docs/agent-rules.md for the rules block it installs (also available via taosmd.agent_rules()).

Multiple agents in one framework? Same install message works. The agent will ask you to name it before registering, so each agent gets its own shelf. The taOSmd service stays one process with one shared set of stores; per-agent isolation is enforced by an agent tag on every row, not by separate files. See docs/multi-agent.md for the full naming convention, project-scoped and cross-agent memory, migration scenarios, and a five-agent worked example.

Inside taOS? Don't use this. taOS provisions taOSmd automatically when you deploy an agent, and the rules block is baked into the agent template. This install path is for standalone framework users.

One-Line Setup (manual)

Install: pip install taosmd (add the MCP server with pip install "taosmd[mcp]"). For a source/dev install instead, git clone then pip install -e .. The one-line bootstrap below additionally installs Ollama and downloads the embedding and LLM models; it is newer and still being validated across clean machines, so please report issues.

curl -fsSL https://raw.githubusercontent.com/jaylfc/taosmd/master/scripts/setup.sh | bash

This will: 1. Clone the repo and install Python dependencies 2. Download the all-MiniLM-L6-v2 ONNX embedding model (90MB) 3. Install Ollama and pull Qwen3-4B for fact extraction + answering (2.6GB) 4. On RK3588: download the NPU-optimised Qwen3-4B RKLLM model instead (4.6GB) 5. Create the data directory and run a self-test

Manual Install

```bash git clone https://github.com/jaylfc/taosmd.git cd taosmd pip install -e .

Install rkllama: https://github.com/NotPunchnox/rkllama

hf download dulimov/Qwen3-4B-rk3588-1.2.1-base \ Qwen3-4B-rk3588-w8a8-opt-1-hybrid-ratio-0.0.rkllm \ --local-dir ~/.rkllama/models/qwen3-4b-chat ```

Install hygiene (avoid a shadowed install)

Always install taOSmd into a virtual environment, and never with sudo into the system Python. A system-wide copy under /usr/lib/python3/dist-packages/taosmd (left by an earlier sudo pip install) will shadow a venv editable install, so import taosmd resolves to the stale system copy instead of your checkout. To check what is actually being imported and remove a stale system copy:

```bash

Install and start (binds 0.0.0.0:7900, installs systemd / LaunchAgent)

./scripts/install-server.sh

Install the client package and point it at the server

./scripts/install-client.sh http://pi.local:7900

Reference Setup (Orange Pi 5 Plus)

This is the author's primary deployment and the exact stack the 97.0% benchmark was measured on. Other tiers (Pi 4B, Intel mini, Mac mini, GPU box) run the same code, they swap the runtime (Ollama instead of rkllama, CPU/GPU instead of NPU) but keep the same models and the same architecture.

Everything in this reference stack runs on the Pi itself; no external server needed for this tier. The Qwen3-4B handles both fact extraction and question answering on the NPU. The ONNX embedding model runs in-process on the CPU. An optional GPU worker (e.g. Fedora with RTX 3060) can accelerate LLM tasks ~10x but is not required, the Pi is fully self-contained.

Platform-Specific Setup

Install rkllama (serves models on the NPU)

The setup script handles this automatically, or manually:

hf download dulimov/Qwen3-4B-rk3588-1.2.1-base \ Qwen3-4B-rk3588-w8a8-opt-1-hybrid-ratio-0.0.rkllm \ --local-dir ~/.rkllama/models/qwen3-4b-chat ```

Install the taOSmd-a2a skill

taosmd install-skill

Copies the bundled taosmd-a2a agent-setup skill into ~/.claude/skills/taosmd-a2a/ so it is available across all Claude Code projects. Pass --force to overwrite an existing installation.

Quick Start

```python from taosmd import KnowledgeGraph, VectorMemory, Archive

Option A (default): any Linux/macOS box with or without a GPU, use Ollama

curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen3:4b

Option B (NPU acceleration): Orange Pi / Rock 5 / Radxa with RK3588, use rkllama

If it points at /usr/lib/... or /usr/local/... instead of your venv, remove it:

sudo python3 -m pip uninstall -y taosmd # the SYSTEM python, outside any venv ```

Running taosmd serve as a systemd unit? Point the unit at your venv's interpreter (ExecStart=/path/to/.venv/bin/python -m taosmd serve ...); a PyPI or venv install needs no WorkingDirectory and no repo checkout to start.

Tag each turn with its position (and optional group, e.g. session)

for i, turn in enumerate(turns): await vmem.add(turn["text"], metadata={"position": i, "session": "conv1"})

hits = await retrieve( "what was discussed about the deploy?", sources={"vector": vmem}, adjacent_neighbors=2, # default 0, opt in for the lever position_key="position", group_key="session", # confine neighbours to the same session )

when the hit lacks the configured position/group keys).

```

Recipes (tier-aware config profiles)

A recipe is a named, declared config bundle (retrieval + ingest + generator + librarian settings) that carries its own benchmark scores, target hardware tier, and pros/cons. Instead of leaving the retrieval levers at their defaults, taOSmd ships a small registry of recipes we have actually measured (for example the maxsim-rerank-9b leader for a 12 GB GPU and a lite-pi no-LLM-ingest profile for an Orange Pi / CPU), and a fresh install auto-detects your hardware and applies the best affordable recipe on first use, so you run a benchmarked configuration rather than unconfigured defaults. No taOS or network is required: the hardware probe is local, and the reranker model (when a recipe asks for one) downloads on first use with progress and degrades gracefully if it is not yet present.

```python import taosmd

Checking and clearing the config

taosmd config show          # print server_url, whether a token is set, memory_model
taosmd config set-server --clear   # revert to local mode

Optional bearer token auth

By default there is no authentication. If the server is on a trusted private network (Tailscale, a home LAN), the network boundary is the access control. For defence in depth, you can require a bearer token:

```bash

Or, to keep the token out of config.json:

export TAOSMD_TOKEN=<your-secret-token> ```

The token is sent as Authorization: Bearer <token> on every request. GET /health and the web inspector (GET /) are always public so monitoring probes keep working. Never commit the token to version control.

Optional: GPU Worker (x86 + NVIDIA)

Not required for any tier, the LLM runs locally on whatever you've got. A GPU worker accelerates LLM tasks ~10x if you want to offload from a smaller node:

```bash

How the Python API and MCP server interact with remote mode

The RemoteClient class (taosmd.remote) mirrors the same async interface as the local service module (taosmd.service). The CLI, Python API, and MCP server all check TAOSMD_SERVER_URL (and config.json) at startup and delegate to RemoteClient when a URL is configured. From the caller's perspective nothing changes: the same taosmd.ingest(), taosmd.search(), and A2A calls work in both modes.

API

taosmd serve starts a local HTTP/REST server (default 127.0.0.1:7900, stdlib only, no new dependencies). It is a thin JSON shell over the same service layer as the Python API and CLI, so behaviour is identical across surfaces. Every endpoint that takes an agent parameter forwards it to the service layer, honouring the same per-agent isolation as the Python API.

Security note: the server binds 127.0.0.1 by default, no auth is needed because only local processes can reach it. If you pass --host 0.0.0.0 to expose it on a LAN, there is no authentication; put it behind your own network controls.

Endpoints

Each hit in /search results has the agent-rules contract shape: {text, source, timestamp, confidence, metadata}.

/ingest/batch is the bulk-import path: each item can carry a stable id (your content hash), preserved as source_id and used to skip already-imported items, so the whole batch can be re-POSTed safely after a partial migration. mode=bm25 on /search skips query embedding entirely and returns keyword-ranked hits in about 10ms, built for search-as-you-type UIs over short-form memory; the default mode remains the full recipe-driven retrieval.

Fusion Strategy Comparison

Full LongMemEval-S benchmark (500 questions)

python benchmarks/longmemeval_runner.py

LoCoMo (1540 QAs, multi-session conversations)

python benchmarks/locomo_runner.py --model gemma4:e2b