Skip to main content
Glama
semantica

semantica

by sin3000x

Semantica agent 接入入门

这是一个可以直接运行的 Semantica 小项目,专门回答一件事:

agent 是怎么接到 Semantica 上的?

结论先说清楚:

  • Semantica 不是 agent 框架。

  • 它不调度工具、不跑 ReAct、不管理 multi-agent 对话。

  • 它是 agent 下面的语义层:记忆、知识图谱、决策审计。

  • 任何 agent(自己写的循环、Agno、LangChain、CrewAI、Claude、Cursor)都通过同一组插头接入。

你的 agent(自己写 / Agno / LangChain / CrewAI / Claude)
        │
        ├── memory     AgentContext.store / list
        ├── knowledge  ContextGraph.add_node / query
        ├── decisions  record_decision / 因果链
        └── tools      框架 Toolkit 或 MCP
        ▼
   Semantica

五课默认不需要 LLM。第 2 课的决策可以额外接本地 runtime 或云端 API key,两者走同一条 OpenAI 兼容插头。

0. 环境

  • Python 3.11+

  • uv

Intel macOS 会自动钉住仍提供 x86_64 轮子的 torch / onnxruntime / numba。其它平台由 Semantica 自己解析依赖。

Related MCP server: Spomory

1. 安装

git clone https://github.com/sin3000x/semantica-agent-starter.git
cd semantica-agent-starter
uv sync

验证:

uv run python --version
uv run python -c "import semantica; print(semantica.__version__)"
uv run python main.py doctor

第一次创建 VectorStore 可能下载 embedding 模型;第一次导入 Semantica 也会比较慢。

2. 开始上课

uv run python main.py
uv run python main.py 1

课

做什么

1

插头就是 AgentContext:写入记忆 + record_decision

2

采购 agent:感知 → 查先例 → 决策 → 落盘

3

两个 agent 不发消息,读写同一张 ContextGraph

4

Agno / LangChain / CrewAI 只是把四个插座包成框架对象

5

Claude / Cursor 走 MCP:python -m semantica.mcp_server

uv run python main.py all

3. 可选:接 LLM(runtime 或 API key)

第 2 课默认用规则:延期天数 > 库存天数 就升级。规则一直可测、可回退。

配置了 LLM 之后,decide() 会先问模型;解析失败或连不上就退回规则。Semantica 仍然只负责记住决定。

复制环境文件:

cp .env.example .env

本地 runtime(无 key)

OpenCode 是一等 runtime:默认调用本机 opencode run,用你已经 opencode auth login 过的模型,不必再配一份 API key。

# 先装 OpenCode,并完成登录
# curl -fsSL https://opencode.ai/install | bash
# opencode auth login

SEMANTICA_LLM=opencode
# 可省略,缺省用 OpenCode 当前默认模型
# SEMANTICA_LLM_MODEL=anthropic/claude-sonnet-4-5

已经 opencode serve 时,让 CLI 挂到现有服务上,避免每次冷启动:

SEMANTICA_LLM=opencode
OPENCODE_ATTACH=http://127.0.0.1:4096

若你跑的是 OpenCode 的 OpenAI 兼容代理(例如 opencode-llm-proxy 的 :4010),把地址写成 /v1 即可:

SEMANTICA_LLM=opencode
SEMANTICA_LLM_BASE_URL=http://127.0.0.1:4010/v1

也适合 Ollama、vLLM、LM Studio,以及任何 OpenAI 兼容服务。

# Ollama
ollama pull llama3.1
# .env
SEMANTICA_LLM=ollama
SEMANTICA_LLM_MODEL=llama3.1
OLLAMA_HOST=http://127.0.0.1:11434
# LM Studio / vLLM
SEMANTICA_LLM=compat
SEMANTICA_LLM_BASE_URL=http://127.0.0.1:1234/v1
SEMANTICA_LLM_MODEL=local-model
SEMANTICA_LLM_API_KEY=local

云端 API + key

默认推荐 SpaceXAI / xAI(OpenAI 兼容,XAI_API_KEY)。

XAI_API_KEY=xai-...
# 可省略 SEMANTICA_LLM,有 XAI_API_KEY 就会自动选 xai
SEMANTICA_LLM_MODEL=grok-4.6

也可以用 OPENAI_API_KEY 或 GROQ_API_KEY。探测顺序:显式 SEMANTICA_LLM → XAI_API_KEY → OPENAI_API_KEY → GROQ_API_KEY。

uv run python main.py doctor
uv run python main.py 2

不要把 .env 提交进 git。

4. MCP

配置样例在 mcp/。把 /ABS/PATH/TO/semantica-agent-starter 换成你的克隆路径。

uv run python -m semantica.mcp_server

5. 测试

uv run pytest

tests/test_llm.py 不访问网络。课程测试第一次大约需要几分钟(Semantica 导入和 VectorStore 初始化比较重)。

测试检查的是接入约束:

  • agent 写入的记忆和决定都能读回来

  • 规则 agent 的第二次决定能追溯到第一次

  • 两个 agent 共享同一张图

  • 没配 key 时不会误接 LLM;配了坏响应会回退规则

6. 官方框架怎么接

框架

接到哪

自己写循环

直接调 AgentContext

Agno

AgnoContextStore + AgnoDecisionKit + AgnoSharedContext.bind_agent

LangChain

SemanticaKGTool + SemanticaDecisionTool + SemanticaRetriever

CrewAI

SemanticaKGTool + SemanticaDecisionTool + SemanticaKnowledgeSource

Claude / Cursor

MCP

本项目不安装这些 extra。第四课用一个小适配器把同样的四个插座跑通。

License

MIT

Available Tools

12 tools
add_entityB

Add a node/entity to the Semantica knowledge graph.

Inputs: id (required), type, label, metadata.

add_relationshipB

Add a directed relationship (edge) between two entities in the knowledge graph.

Inputs: source (required), target (required), type, metadata.

export_graphA

Export the current knowledge graph. Formats: turtle, ttl, nt, xml, json-ld, json.

Inputs: format.

extract_entitiesB

Extract named entities (people, places, organisations, concepts) from text using Semantica NER.

Inputs: text (required).

extract_relationsA

Extract relations and (subject, predicate, object) triplets from text.

Inputs: text (required).

find_precedentsB

Find past decisions similar to a given scenario using hybrid similarity search.

Inputs: scenario (required), max_results.

get_causal_chainC

Trace the causal chain upstream or downstream from a decision.

Inputs: decision_id (required), direction, max_depth.

get_graph_analyticsA

Compute PageRank centrality and community detection over the knowledge graph.

Inputs: no named parameters.

get_graph_summaryA

Return a high-level summary of the current knowledge graph: node count, decision count, status.

Inputs: no named parameters.

query_decisionsB

Query recorded decisions by natural language, category, or get all recent decisions.

Inputs: limit, query, category.

record_decisionC

Record a decision into the Semantica knowledge graph with full context, causal links, and metadata.

Inputs: outcome (required), category (required), scenario (required), reasoning (required), +4 more.

run_reasoningA

Run forward-chaining IF/THEN rules over a set of facts to derive new facts.

Inputs: facts (required), rules (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a clearly distinct operation: extraction, knowledge graph mutation, decision querying, reasoning, analytics, and export. There is no meaningful overlap or ambiguity between the tool purposes.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern, such as extract_entities, record_decision, query_decisions, and get_graph_analytics. The naming is predictable and easy to navigate.

    Tool Count5/5

    Twelve tools is well-scoped for a knowledge graph and semantic reasoning server. Each tool covers a distinct capability without unnecessary bloat.

    Completeness3/5

    The tool set covers creation, querying, reasoning, analytics, and export, but lacks update/delete operations for entities, relationships, or decisions. This is a notable lifecycle gap that agents may need to work around.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables personal AI memory management through MCP tools for adding, searching, exporting, and deleting memories, with knowledge-graph retrieval and multi-hop association for clients like Claude Desktop and Cursor.
      6
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to govern and access memory engines over MCP, with scoped read/write permissions, journaling, secret scrubbing, and bounded context delivery at session start.
      MIT