# KnowMe

**Repository Path**: culturedream/know-me

## Basic Information

- **Project Name**: KnowMe
- **Description**: KnowMe 是面向 AI Agent 的用户可控长期记忆系统，支持记忆检索、纠正与遗忘、人物画像、导入导出和隐私审计，并提供 SQLite 运行时及可选 MCP 接口。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KnowMe V2

**A portable Agent Skill plus a runnable personal-context memory runtime.**

KnowMe helps an AI build a careful, evidence-based understanding of a user across conversations. It separates confirmed facts from revisable observations, records provenance, handles correction and deletion, and retrieves only context relevant to the current task.

## What V2 provides

V2 has two distinct layers:

```text
Agent Skill
- when to activate
- what is worth remembering
- how to distinguish facts, relationships and interpretations
- how to retrieve, interview, consolidate, explain and forget

Runtime
- SQLite persistence
- owner and subject isolation
- lexical/FTS retrieval
- evidence records and audit events
- conflict review and supersession
- generated profile views
- CLI and optional MCP tools
```

The Skill is portable across hosts that support the Agent Skills format. A local SQLite vault can be shared by trusted agents on the same machine. Sharing one vault across cloud agents or devices requires an authenticated remote service.

## Highlights

- Standards-compatible `SKILL.md` with YAML frontmatter.
- Python 3.10+ runtime with no required third-party dependencies and an offline bootstrapper.
- Optional MCP Python SDK 2.x adapter.
- SQLite persistence with FTS5 and a multilingual lexical fallback.
- Separate `owner_id` and `subject_id`; generated profiles keep other-subject memories in a clearly labeled section instead of presenting them as user facts.
- Exact deduplication, retry idempotency when source message IDs are supplied, and evidence reinforcement.
- Topic-based conflict review and explicit supersession.
- Facts, preferences, goals, projects, events, decisions, constraints, values and observations.
- Separate relationship edges.
- Capture modes: `off`, `explicit`, `assisted`, `automatic-low-risk`.
- Secret-pattern blocking and consent rules for sensitive memories.
- Prompt-injection-resistant, data-only context rendering.
- Hard delete by default, optional soft deletion, and exact-confirmation full-vault erasure.
- Enforced retention lifecycle for expiring, review-due and session-scoped memories.
- Export, import, audit log and profile views.
- Opt-in interview-gap detection.
- Strict schemas, unit tests and evaluation fixtures.

## Quick start

Zero-dependency local setup (no package index required):

```bash
cd know-me
python scripts/bootstrap.py
source .venv/bin/activate          # Windows: .venv\Scripts\activate
```

Conventional editable installation is also supported when Python packaging tools are available:

```bash
pip install -e .
```

Initialize a vault:

```bash
knowme init \
  --owner-id jason \
  --display-name "Jason" \
  --capture-mode explicit
```

Create a candidate file from the included example:

```bash
cp examples/memory-candidate.json /tmp/knowme-candidate.json
```

Edit `owner_id`, then persist it:

```bash
knowme remember --file /tmp/knowme-candidate.json --write-intent explicit-command
```

Search and render safe prompt context:

```bash
knowme search --owner-id jason --query "current AI priorities"
knowme context --owner-id jason --query "current AI priorities"
```

Generate a profile:

```bash
knowme profile --owner-id jason --format markdown
knowme profile --owner-id jason --format json
```

Inspect and enforce retention lifecycle:

```bash
knowme lifecycle --owner-id jason
knowme purge-expired --owner-id jason
knowme close-session --owner-id jason --conversation-id conv_xxx
```

Correct or forget:

```bash
knowme correct --owner-id jason --memory-id mem_xxx --claim "Corrected claim"
knowme forget --owner-id jason --memory-id mem_xxx            # hard delete
knowme forget --owner-id jason --memory-id mem_xxx --soft     # tombstone only
knowme delete-vault --owner-id jason --confirm-owner-id jason # erase entire vault
```

See [examples/quick-demo.md](examples/quick-demo.md) for an end-to-end source-checkout demo.

Export and import a portable vault:

```bash
knowme export --owner-id jason --output /tmp/jason-knowme.json
knowme import --owner-id jason-copy --file /tmp/jason-knowme.json
```

`private` and `restricted` records are excluded from export unless `--include-sensitive` is used. Restricted records in an import archive are skipped by default and require a separate, visible override:

```bash
knowme export --owner-id jason --output /tmp/jason-private.json --include-sensitive
knowme import --owner-id jason-copy --file /tmp/jason-private.json --allow-restricted
```

Imported payloads are treated as untrusted input. The runtime revalidates claims, skips secret-like provenance excerpts, and does not preserve source IDs as trusted local identifiers.

## Optional MCP server

```bash
pip install -e ".[mcp]"
export KNOWME_OWNER_ID=jason
knowme-mcp
```

The local server exposes owner-scoped tools for initialization, capture-mode control, search, safe context rendering, remembering, metadata updates, correction, deletion, lifecycle enforcement, export/import, audit, profile generation, interview gaps, relationship management and diagnostics.

The bundled server is stdio-only and requires `KNOWME_OWNER_ID` at startup, binding the process to one owner. It does not authenticate end users and must not be exposed directly to the public internet. An unbound development override exists only for isolated testing.

## Capture modes

| Mode | Expected host behavior |
|---|---|
| `off` | Do not extract or persist automatically. |
| `explicit` | Save only after a direct user request or confirmation. |
| `assisted` | Propose candidates and save after approval. |
| `automatic-low-risk` | A host hook may save only normal-sensitivity, explicit, durable claims. |

An Agent Skill is selected on demand. It cannot guarantee automatic execution after every message by itself. Continuous memory requires a before/after-turn hook, middleware, plugin or agent runtime. See [references/runtime-integration.md](references/runtime-integration.md).

## Data location

Default local database:

```text
~/.know-me/knowme.db
```

Override it with:

```bash
export KNOWME_DB=/secure/path/knowme.db
```

`KNOWME_DB_PATH` is accepted as a backward-compatible alias.

On supported Unix-like systems, the runtime attempts to apply `0700` to the vault directory and `0600` to the database file. SQLite `secure_delete` is enabled and hard deletes make a best-effort WAL truncation.

**The reference SQLite database is not encrypted at rest.** Secure deletion is not a substitute for full-disk encryption or SQLCipher in sensitive deployments.

## Repository layout

```text
know-me/
├── SKILL.md
├── README.md
├── README.zh-CN.md
├── INSTALL.md
├── pyproject.toml
├── agents/openai.yaml          # optional OpenAI-facing UI metadata
├── src/knowme/
├── scripts/                    # CLI launchers, bootstrap, validation
├── references/
├── schemas/
├── assets/
├── evals/
├── tests/
├── examples/
└── integrations/
```

## Validation

```bash
python scripts/run_tests.py
```

This validates the Skill manifest and references, parses schemas and eval fixtures, compiles Python sources, and runs the unit tests.

## Important limitations

1. Secret detection is defensive, not exhaustive.
2. The reference search is lexical/FTS-based rather than embedding-based.
3. The local CLI trusts the operating-system user; it does not authenticate people.
4. The bundled MCP server is a local reference adapter, not a hosted multi-tenant service.
5. A remote shared vault needs authorization, encryption, tenant isolation, rate limiting and concurrency control.
6. Personality-like observations remain model interpretations and should always be reviewable and reversible.
7. KnowMe is not a medical, psychological, legal, employment, credit or insurance scoring system.

## Product principle

> Remember less, understand better, and remain willing to be corrected.